Macromedia BREEZE 5 INTEGRATION GUIDE

Breeze Integration Guide

Trademarks

1 Step RoboPDF, ActiveEdit, ActiveTest, Authorware, Blue Sky Software, Blue Sky, Breeze, Breezo, Captivate, Central, ColdFusion, Contribute, Database Explorer, Director, Dreamweaver, Fireworks, Flash, FlashCast, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, HomeSite, JRun, MacRecorder, Macromedia, MXML, RoboEngine, RoboHelp, RoboInfo, RoboPDF, Roundtrip, Roundtrip HTML, Shockwave, SoundEdit, Studio MX, UltraDev, and WebHelp are either registered trademarks or trademarks of Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally.

Third-Party Information

This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia endorses or accepts any responsibility for the content on those third-party sites.

Copyright © 1997-2005 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced, translated, or converted to any electronic or machine-readable form in whole or in part without written approval from Macromedia, Inc. Notwithstanding the foregoing, the owner or authorized user of a valid copy of the software with which this manual was provided may print out one copy of this manual from an electronic version of this manual for the sole purpose of such owner or authorized user learning to use such software, provided that no part of this manual may be printed out, reproduced, distributed, resold, or transmitted for any other purposes, including, without limitation, commercial purposes, such as selling copies of this documentation or providing paid-for support services.

Acknowledgments

Director: Erick Vera

Project Management: Stephanie Gowin

Writing: Jody Bleyle

Managing Editor: Rosana Francescato

Editing: Linda Adler, Geta Carson, Evelyn Eldrige, Mary Ferguson, Lisa Stanziano, Jessie Wood

Production and Editing Management: Patrice O’Neill

Media Design and Production: Adam Barnett, John Francis

First Edition: May 2005

Macromedia, Inc. 601 Townsend St.

San Francisco, CA 94103

INTRODUCTION: Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

What’s new in the Breeze XML APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

What’s changed in the Breeze XML APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Guide to instructional media . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

CHAPTER 1: Using the Breeze XML APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Data flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Calling an API on the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

About parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

About principals, SCOs, and IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

About security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

CHAPTER 2: Working with Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

About filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

About sort filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Special filter scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Filter reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Testing code in the browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Where to go from here . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

CHAPTER 3: Common Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Calling your first API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Logging in to Breeze . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Creating a new user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Adding a user to a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Displaying a user’s meetings, courses, and events . . . . . . . . . . . . . . . . . . . . . . . . . 31

Creating a meeting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Creating a meeting from a template. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Creating and managing learning paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Integrating Breeze with a directory service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Integrating Breeze with a portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Generating reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

CHAPTER 4: XML API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Sample API entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

API listing by function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Alphabetical API listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

API reference entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

accesskey-exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

accesskey-info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

acl-field-info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

acl-field-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

acl-field-update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

acl-preference-update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

action-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

common-info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

custom-field-update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

custom-fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

custom-fields-delete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

group-membership-update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

learning-path-info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

learning-path-update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

permissions-info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

permissions-reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

permissions-update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

principal-info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

principal-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

principal-list-by-field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

principal-update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

principals-delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

report-account-meeting-attendance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

report-active-meeting-presenters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

report-active-meetings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

report-bandwidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

report-bulk-consolidated-transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

report-bulk-content-quiz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

report-bulk-content-quiz-results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

report-bulk-content-slide-views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

report-bulk-course-quiz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

report-bulk-course-results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

report-bulk-meeting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

report-bulk-meeting-attendance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

report-bulk-objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

report-bulk-questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

report-bulk-slide-views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

report-bulk-users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

report-course-status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

report-course-takers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

report-disk-usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

report-meeting-attendance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

4 Contents

report-meeting-concurrent-users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

report-meeting-session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

report-meeting-sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

report-meeting-session-slots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

report-meeting-summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

report-my-courses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

report-my-events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

report-my-meetings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

report-principal-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

report-quiz-answer-distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

report-quiz-definition-answers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

report-quiz-definition-questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

report-quiz-interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

report-quiz-question-answer-distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

report-quiz-question-distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

report-quiz-question-response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

report-quiz-question-totals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

report-quiz-summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

report-quiz-takers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

report-quotas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

report-sco-slides. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

report-sco-views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

report-survey-question-response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

sco-build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

sco-contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

sco-delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

sco-expanded-contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

sco-info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

sco-move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

sco-nav . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

sco-search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

sco-shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

sco-update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

sco-upload. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

user-accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

user-transcript-update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

user-update-pwd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

CHAPTER 5: XML Results Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

About returned XML code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Sample XML tag entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

Alphabetical list of XML tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

access-key (container) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

access-key (key) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

access-key-group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

access-keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

acl-field-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Contents 5

acl-fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

answer-correct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

answer-text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

comment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

common . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

course . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

custom-fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

date-begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

date-closed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

date-created. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

date-end . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

date-expired. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

date-last-taken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

date-modified . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

date-taken . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

date-time-attempted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

domain-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

duration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

expanded-scos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

expired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

field. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

first-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

hit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

host . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

invalid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

last-name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

last-viewed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

last-viewed-date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

learning-path. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

learning-paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

meeting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

most-recent-session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

my-courses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

my-events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

my-meetings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

participant-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

path. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

6 Contents

permission. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

physical-path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

preferences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

presentation-name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

principal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

principal-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

principal-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

question-text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

quiz-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

quiz-definition-answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

quiz-definition-questions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

quiz-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

quota. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

report-account-meeting-attendance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

report-active-meeting-presenters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

report-active-meetings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

report-bandwidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

report-bulk-consolidated-transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

report-bulk-content-quiz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

report-bulk-content-quiz-results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

report-bulk-course-quiz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

report-bulk-course-quiz-results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

report-bulk-meeting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

report-bulk-meeting-attendance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

report-bulk-objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

report-bulk-questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

report-bulk-slide-views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

report-bulk-users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

report-course-status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

report-disk-usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

report-meeting-attendance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

report-meeting-concurrent-users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

report-meeting-session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

report-meeting-sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

report-meeting-session-slots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

report-meeting-summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

report-principal-list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

report-quiz-answer-distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

report-quiz-interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

report-quiz-question-answer-distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

report-quiz-question-distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

report-quiz-question-response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

report-quiz-question-totals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

report-quiz-results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

report-quiz-summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

report-quiz-takers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

report-quotas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

report-sco-slides. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Contents 7

report-sco-views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

report-survey-question-response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

report-training-concurrent-users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

sco. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

sco-author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

sco-data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

sco-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

sco-nav . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

sco-search-info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

scos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

source-sco . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

time-slot-begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

time-slot-end. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

time-taken. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

url . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

url-path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

user (common-info) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

user (user-accounts). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

user-agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

user-first-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

user-last-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

user-login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

user-name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

view-date-time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

8 Contents

INTRODUCTION

Before You Begin

The Macromedia Breeze XML web services enable your external system (such as a web application) to interact with a Breeze server.

This manual provides information on how to call XML web services (also called APIs or actions) on the Breeze server from your external system and how to interpret the XML results that Breeze returns. This manual also contains reference material explaining what each application programming interface (API) does and what its parameters are.

Audience

This manual is intended for developers who want to integrate the Breeze XML web services into their external systems, such as web applications.

Before you use this manual, you should understand the basics of XML and of using HTTP requests to communicate between an application and a server. You must also understand how to program using a server language such as Macromedia ColdFusion Markup Language (CFML).

What’s new in the Breeze XML APIs

Custom field APIs let you add, update, and get information about custom fields: acl-field-

, acl-field-list, acl-field-update.

info

New Report APIs let you gather data from the Breeze server: report-bulk-consolidated-

transactions

, report-bulk-users, report-bandwidth, and report-my-events.

views

Updated Report-quiz APIs include new interaction data types: report-quiz-interactions,

report-quiz-question-answer-distribution, report-quiz-question-distribution, report-quiz-question-response.

Updated Principals APIs include information about custom fields.

Updated SCO APIs include new shareable content object (SCO) and content types.

New SCO API lists all of the SCOs in an account. Use the sco-expanded-contents API with

filters to locate particular SCOs.

Curriculum APIs let you gather information about and update curriculums: learning-path-

, learning-path-update.

info

, report-bulk-objects, report-bulk-questions, report-bulk-slide-

What’s changed in the Breeze XML APIs

Some APIs that were supported in Breeze 4 are no longer supported in Breeze 5. For information about alternate APIs, where available, see the individual entries in Chapter 4, “XML API

Reference,” on page 41. The following APIs are no longer supported in Breeze 5:

• accesskey-exec

• accesskey-info

• report-account-meeting-attendance

• report-bandwidth

• report-bulk-content-quiz

• report-bulk-content-quiz-results

• report-bulk-content-slide-views

• report-bulk-course-quiz

• report-bulk-course-results

• report-bulk-meeting

• report-bulk-meeting-attendance

• report-course-takers

• report-disk-usage

• report-meeting-session

• report-meeting-session-slots

• report-principal-list

• report-quiz-answer-distribution

• report-quiz-definition-answers

• report-quiz-definition-questions

• report-quiz-question-totals

Guide to instructional media

Breeze contains a variety of media to help you quickly learn how to use the product. In addition to this manual, the following electronic manuals and online help systems are available:

• Breeze Installation and Configuration Guide describes how to install the Breeze applications.

This manual is available as a DVD insert for enterprise users, and as a PDF on the DVD.

• Breeze Manager User Guide describes how to use the administration, presentation, and training

applications of Breeze Meeting. You can access Breeze Manager User Guide from the Breeze Manager home page and from the Help link in the Breeze Manager web application.

10 Introduction: Before You Begin

• Breeze Meeting User Guide for Hosts and Presenters includes information about using the Breeze

Meeting web application to host online real-time meetings. The documentation includes procedures that demonstrate the simplicity of adding slides, Flash SWF files, images, live audio, and video to your presentation. You can access Breeze Meeting User Guide for Hosts and Presenters from the Breeze Manager home page and from the Help menu within a Breeze Live meeting room (when you enter as a presenter).

• Breeze Meeting User Guide for Participants contains information that is relevant to users who are

participating in an online real-time meeting. Breeze Meeting offers participants several options to make their experience truly participatory, including the ability to send messages and questions to presenters and to each other, and the ability to participate through live video and audio. You can access Breeze Meeting User Guide for Participants from the Breeze Manager home page and from the Help menu within a Breeze Live meeting room (when you enter as a participant).

• Using the Macromedia Breeze Presenter describes the plug-in that allows you to create Breeze

presentations from PowerPoint. You can access Using the Macromedia Breeze Presenter from the Breeze Manager home page and from the Breeze menu in Microsoft PowerPoint by selecting Breeze > Help.

Note: The relevance of these guides to users depends on the applications installed on the Breeze Presentation platform, the type of user (such as meeting content manager, information technology engineer, or course presenter), and the user’s Breeze account permissions.

Additional resources

The following list contains some useful resources that are available on the web:

The Breeze Developer Center at macromedia.com (www.macromedia.com/devnet/breeze/)

provides sample code and articles about Breeze integration.

The Web Services Primer at xml.com (http://webservices.xml.com/pub/a/ws/2001/04/04/

webservices/) is a good introduction to web services.

“Working with XML and ColdFusion” in the ColdFusion Developer’s Handbook

(www.macromedia.com/devnet/mx/coldfusion/articles/cf_handbk_ch6.html) provides information about XML basics and creating XML code using CFML.

“Leveraging XML with ColdFusion” (www.macromedia.com/devnet/mx/coldfusion/articles/

cf_handbk_ch7.html) discusses web services, Simple Object Access Protocol (SOAP), and how to

call web services using CFML.

The XSL Transformations (XSLT) specification (www.w3.org/TR/xslt) introduces XSLT,

which you can use to convert formatted data to other formats.

Numeric Representation of Dates and Time (www.iso.ch/iso/en/prods-services/popstds/

datesandtime.html) provides information about the ISO 8601 standard date and time format.

More specifically, the W3C note about dates and times (www.w3.org/TR/NOTE-datetime) provides information about the profile of ISO 8601 that Breeze uses.

Additional resources 11

Typographical conventions

The following typographical conventions are used in this manual:

• Italic font indicates a value that should be replaced (for example, in a folder path).

• Code font indicates code. It also indicates names of APIs, names of parameters, names of tags,

and names of attributes.

• Boldface font indicates a verbatim entry.

12 Introduction: Before You Begin

CHAPTER 1

Using the Breeze XML APIs

The Macromedia Breeze XML application programming interface (API) model exposes interfaces as a set of XML web services. These services let your external system (such as a portal application) communicate with the Breeze server, using HTTP or HTTPS to call APIs on the server and to receive results formatted as XML code. You can use the web services to add Breeze management and reporting capabilities to your external system. To call the Breeze XML APIs, you can use any language that can use XML over HTTP.

Note: Breeze doesn’t currently support Simple Object Access Protocol (SOAP).

This chapter describes the flow of data between the Breeze server and web applications and how you set parameters and security permissions.

Data flow

The following diagram shows an example of the flow of data in a web application that interacts with the Breeze server:

Web browser

Step 1: Web browser requests page.

Step 2: Web server finds page and passes it to application server.

Step 3: Application server executes code.

Step 4: Application server calls API on Breeze server.

Request

<HTML>

<code>

</HTML>

Action

WEB SERVER

Application server

Response

XML data

Step 7: Web server sends finished page to requesting browser.

Step 6: Application server inserts data in page and then passes the page to the web server.

Step 5: Breeze server returns XML data to application server.

Breeze Server

The following example describes what might happen when a user connects to a training portal intranet site that was created with Macromedia ColdFusion MX and that uses Breeze XML web services:

A logged-in user uses a web browser to request a page that shows a list of the courses that the user is signed up for.

The web server finds the relevant page and passes it to the application server.

The application server parses and executes the ColdFusion code contained in the page.

14 Chapter 1: Using the Breeze XML APIs

As part of executing the code, the application server calls an API on the company’s Breeze server, requesting the list of courses. The API call takes the form of an HTTP

The Breeze server executes the API, returning the resulting XML data to the application server.

The application server code parses the returned XML, inserts data into the web page as

POST request.

appropriate, and then passes the finished page to the web server.

The web server passes the finished page to the browser to be displayed.

Calling an API on the server

To call an API on the Breeze server, pass the relevant parameters to the web services servlet at http://server_name/api/xml. To call the Breeze XML APIs, you can use any language that can use XML over HTTP.

There is one parameter that is required for all APIs: the parameter named the name of the API. You append the

action parameter to the web services servlet URL with a

action, which specifies

query string, as follows:

http://server_name/api/xml?action=action_name

Most APIs also have other parameters. For more information about additional parameters for a given API, see the documentation for that API in Chapter 4, “XML API Reference,” on page 41.

You can send the parameters to the server in either of the following ways:

• Create a query string—a URL that includes query parameters—and send it to the server as an

HTTP

GET or POST request, with the HTTP content type set to application/

x-www-form-urlencoded

. (When you use this approach, in most cases you don’t need to

explicitly set the content type.)

The URL to use for the query string has the form

xml?action=action_name

, with the parameters of the API appended as additional query

http://breeze.example.com/api/

parameters separated by ampersands (&).

• Create an XML object containing the parameter data as param tags contained in a params tag,

and then send an HTTP

or application/xml.

xml

The following code calls the

http://admin.breezecentral.com/api/

xml?action=login&login=jon@doe.com&password=foobar

The following is the equivalent call using POST instead of GET:

<param name="action">login</param> <param name="login">jon@doe.com</param> <param name="password">foobar</param>

</params>

For example code demonstrating how to call an API, see Chapter 3, “Common Tasks,” on

page 27.

POST request to the server, with the HTTP content type set to text/

Calling an API on the server 15

Note: The example code in this book uses the query parameters approach, both for readability and because of limitations in using Macromedia ColdFusion Markup Language (CFML) to send XML objects containing parameter data. Macromedia recommends using the Because of the way that HTTP implements GET and POST, using POST may provide higher security levels than passing parameters in the query string. For more information, see “About security”

on page 18.

POST method when possible.

Logging in to Breeze first

To call most APIs, you must be acting as a particular logged-in user, so you must call the API before you can call most other APIs. (You can call the following APIs without logging in:

action-list, common-info, login, and user-accounts.)

When you log in, the Breeze server returns XML results, which indicate a successful login. The HTTP headers of those results include a cookie called results of a

BREEZESESSION cookie in every subsequent request that you make as that logged-in user; if you

BREEZESESSION. When you receive the

don’t supply the cookie, the API fails. For examples of how to do this, see “Logging in to Breeze”

on page 29.

Your application can log in multiple users and can call APIs for any of those users. For example, when an ordinary user is using your application, you may want to authenticate as that user and call APIs using that user’s credentials, while also keeping an administrative user logged in to perform tasks that require higher levels of permissions.

For more information about security in Breeze, see “About security” on page 18.

About parameters

For most APIs, you can specify one or more additional parameters. (The action parameter is required. For more information, see “Calling an API on the server” on page 15.)

You usually specify parameters as name-value pairs, but the exact process depends on the details of the language you use to call the API on the Breeze server. For sample code in ColdFusion Markup Language (CFML), see Chapter 3, “Common Tasks,” on page 27.

In the documentation for each API, all listed parameters are required except for those that are specifically marked as optional.

For some APIs, you can provide multiple parameters with the same name. For example, the

principals-delete API takes a parameter named principal-id; you can specify multiple

principal-id name-value pairs (each with the name principal-id) when you call the API on

the Breeze server.

The following CFML code example shows how to delete two specified users in a single API call, by specifying two and

loginCookie, which you would set during the login process. For more information, see

principal-id parameters. (This example relies on variables called baseurl

“Integrating Breeze with a directory service” on page 33.)

<cfset idOne=12345> <cfset idTwo=23456> <cfhttp url="#baseurl#api/xml?action=principals-delete&principal-

id=#idOne#&principal-id=#idTwo#" method="post">

16 Chapter 1: Using the Breeze XML APIs

</cfhttp>

In some other APIs, you can provide multiple sets of parameters. For example, the group-

membership-update

API takes parameters named group-id, principal-id, and is-member. To make multiple updates in a single call, you specify each of those parameters for principal and group, and then specify them (using the same parameter names again) for another, and so on.

About principals, SCOs, and IDs

There are two basic kinds of entities in Breeze: principals and Shareable Content Objects (SCOs).

A principal is any entity that can have permissions that control how it interacts with SCOs. The most common types of principals are user (a specific user) and group (a

There are other types of principals, known as Built-in groups: Administrators, Authors, Training Managers, Event Managers, Meeting Hosts, and Seminar Hosts.

You can create users and groups and modify their permissions. You can add users and groups to Built-in groups, but you can’t modify the permissions of a Built-in group. For more information about Built-in groups, see Breeze Manager User Guide.

A SCO is a Breeze document, such as a meeting or an event; folders are also SCOs. Breeze includes the following SCO types:

SCO Description

content A viewable file or collection of files uploaded to the Breeze server (for example,

an FLV file, a SWF file, or an image, pod, or HTML file).

curriculum A Breeze curriculum.

event A Breeze event.

folder A folder on the server’s hard disk that contains Breeze content.

link A reference to another SCO. These are used by curriculums to link to other

SCOs. When content is added to a curriculum, a link is created from the curriculum to the content.

meeting A Breeze meeting.

tree The root of a folder hierarchy. A tree’s root is treated as an independent

hierarchy; you can’t determine the parent folder of a tree from inside the tree.

group of users).

Each principal and SCO has a unique ID number. When you call an API that uses an entity’s ID as a parameter, the parameter name indicates what kind of entity the ID belongs to, but the ID remains the same, regardless of the parameter name. Parameter names for IDs include

folder-id, group-id, parent-acl-id, principal-id, sco-id, and user-id.

For example, to update a user’s password, call the as the

user-id parameter. To determine a user’s name, call the principal-info API, and give

the user’s ID as the

principal-id parameter.

user-update-pwd API, and give the user’s ID

About principals, SCOs, and IDs 17

acl-id,

There are a few other kinds of IDs that aren’t associated with a principal or a SCO, such as

account-id, answer-id, permission-id, and question-id. But in most cases, a parameter

name that ends in

-id indicates that the value of the parameter is the ID of either a principal or

a SCO.

About security

The security model in Breeze ensures that any code calling a given API is authorized to do so. Almost every API call must include a cookie that represents a specific logged-in user. For more information, see “Logging in to Breeze first” on page 16.

For information about the possible status codes that the server can return, see the

About permissions

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

A permission mapping, indicating what permissions a particular principal has for a particular SCO, is called an access control list or ACL. An ACL is an object that is capable of having permission mappings between the object and a principal, but it may not have any mappings at all. An ACL consists of three pieces of information: the ID of a SCO, principal, or account (usually referred to in this context as an ACL ID); the ID of a principal; and a keyword that indicates what the permissions are (usually referred to as a permission ID).

There are two kinds of permissions in Breeze: permissions associated with specific SCOs, and permissions that belong to all users who are members of special groups that are called Built-in groups. Permissions for Built-in groups take precedence over the permissions set on a SCO.

To find out what permissions a logged-in user has for a particular item, call the

permissions-info API. To change a principal’s permissions, call the principal-update API.

status tag.

If a particular principal has no explicitly specified permissions on a particular SCO, that principal’s permissions on the parent of the SCO apply.

18 Chapter 1: Using the Breeze XML APIs

You can specify the following permissions on a SCO:

Permission Description

Denied The principal cannot view, access, or manage the SCO. You cannot specify this

Host (For meetings only) The host of a meeting. This permission lets the principal

Manage The principal can view, delete, move, and edit the SCO. This permission also lets

Publish The principal can publish the SCO to the server and can update the SCO. This

View The principal can view the SCO but not modify it. For a course, the View

permission on meetings or courses.

create or present the meeting, even if the principal doesn’t have View permission on the parent folder of the meeting.

The Presenter permission is now an alias for Host. A presenter in Breeze 4 presenter is a host in Breeze 5.

the principal set permissions for the SCO. For a folder, the Manage permission lets the principal view reports for files in the folder and create new folders. You cannot specify this permission on meetings or courses.

permission includes the View permission. It also lets the principal view reports related to the SCO. For a folder, the Publish permission doesn’t let the principal create new folders within the folder or set permissions for the folder. You cannot specify this permission on meetings or courses.

permission lets the principal enroll in the course. For a meeting, the View permission lets the principal attend the meeting. For a folder, this permission lets the principal view the contents of the folder.

Because a group is a principal, you can set these permissions on a SCO for a custom group as well as for an individual user; if a group has a particular permission, all members of the group have that permission. Use the

permissions-update API to set a group’s permissions for a particular SCO.

group-membership-update API to add a member to a group. Use the

For more information about groups and permissions, see Chapter 19, “Working with Users and Groups,” in Breeze Manager User Guide.

About security and launching content

When you launch a SCO, you must provide authentication. You can do so using any of the following approaches:

• When you open the URL of the content, add a query parameter named session with a value

equal to the value of the

http://breeze.example.com/p12345678/?session=breez3238uf298

This approach is a potential security problem because anyone who obtains the specified URL can act as the logged-in user. If you take this approach, use the cookie for an ordinary user rather than the cookie for an administrative user.

Also, if users give the URL to someone else (for example, by copying it and pasting it into an e-mail message), they are giving access to their account, which presents a security risk.

BREEZESESSION login cookie, as the following example shows:

About security 19

• You c an s et a BREEZESESSION cookie on the user’s browser, using the value of the login cookie.

However, this approach works only if your application is running on a server with the same domain name as the Breeze server.

Also, if your application server is a J2EE servlet environment (such as Macromedia ColdFusion or Java), the application server might also use a cookie named

BREEZESESSION, which results

in potential conflicts between Breeze and the application server.

• You can simply open the URL, and require the user to log in again.

This approach is more secure than the others but can result in some inconvenience for users.

20 Chapter 1: Using the Breeze XML APIs

CHAPTER 2

Working with Filters

The data and information in your company’s Macromedia Breeze content repository can grow significantly over time. When this occurs, you might not want to list every item in the repository for all users. For example, you could list the most recently created courses and the latest quarterly financial results presentation on your company’s intranet. You need to sort and organize your growing repository to ensure that users quickly find the information they are seeking.

Filters are the mechanism within Macromedia Breeze XML web services that you can use to define the criteria for retrieving data from Breeze. You use one or more filters with a specific XML API to ensure that the data your users see matches exactly what they are seeking.

About filters

You can filter for many (but not all) fields in the XML, and you can filter to include values for that field or exclude values for that field. You can also sort the results and filter the return set to include less results, for example, the first 25 rows that match.

Filters work with action calls to modify or organize the data that the Breeze server returns. Filters help you select data, exclude data, and even sort the data you need to see. For example, you can request all your courses or use a filter to select only courses that include the word “Java”; you can list all users or select only users with the last name Smith and sort by their login name.

To use a filter, append it to an action call with an ampersand (&), as in the following:

report-my-course&filter-like-name=Java

You can string multiple filters together, each separated by an ampersand (&), as in the following:

report-my-course&filter-like-name=Java&sort-date-begin=desc

As you can see, filters comprise a type (either filter or sort) with an optional modifier (for example, field name (for example,

Type-Modifier-FieldName=Value

There are two types of filters, a basic filter, which begins with the word filter, and a sort filter, which begins with the word achieve your desired results. For more information about sort filters, see “About sort filters”

on page 23.

like), the name of the field (for example, name), if needed, and finally, the value of the

Java). The following is the filter format:

sort. You can combine sort filters and regular filters as needed to

Filter examples

The following is a simple example to help illustrate the general concept of filters. The web service API

report-my-courses returns the list of courses that you enrolled in. This same API used with

a filter on the course name, for example

report-my-courses&filter-like-name=Java,

retrieves your courses with the specified text in the name, in this case Java. If you add a sort filter such as

report-my-course&filter-like-name=Java&sort-date-begin=desc, Breeze sorts

your Java courses and displays the course you started first.

In these examples, there are two types of filters: filter and sort. The basic filter uses the modifier on the

name field with a value Java. If you omit the like modifier, Breeze returns

courses with the exact name Java instead of courses with Java in the name. Using the sort filter without a modifier on the

date-begin field with a value desc specifies a descending order.

The following table lists a few more examples that are helpful for understanding filter basics:

Filter Description

filter-name=Goals Review

filter-like-name=Goals

filter-out-name=Status

filter-like-name=Goals &filter-out-

status=active

filter-gt-date-begin=2004-05-01&sort-

name=asc

filter-gt-date-begin=2004-05-

01&filter-lt-date-begin=2004-05-31

Returns items from the server that have the specific name “Goals Review.” This may apply to meetings, courses, or any items with a name field.

Returns all items with “Goals” in the name such as “Goals Review” or “Quarterly Goals.”

Filters out or excludes any items with the word “Status” in the name field.

Returns all items with “Goals” in the name that are no longer active; for example, to find previous presentations on “Goals” from previous quarters.

Returns all items with a begin date later than May 1, 2004, sorted by name in ascending order.

Returns all items started in the month of May, 2004.

About date formatting

In Breeze, dates are a special type of field value that follow the ISO 8601 format. For example, May 28, 2004 is expressed as

28T16:23:00.000

. Starting with the year, you can use as much of the date as you need to filter

the best result. Using a value of

2004-05-28, and 4:23 pm on May 28, 2004 is expressed 2004-05-

2004 returns all items that match the same year, which is probably

not a good use of filters. You can retrieve everything that happened in a month by specifying the year and month. You add as much of the date as you need to select the most accurate data from the server.

22 Chapter 2: Working with Filters

About sort filters

You can use a filter of the type sort to sort data in ascending and descending order. For example, the following filter sorts the

sort-name=asc

name field in ascending order:

The following code sorts the name field in descending order:

sort-name=desc

You can also perform primary and secondary sorts. For example, when calling the principal-

action to list principals, you can do a primary sort on the type field, and then a secondary

list

sort on the

name field (this way, all principals of a specific type are grouped together and sorted by

name in each group).

You can do this by specifying the following parameters:

sort1-type=asc&sort2-name=desc

Special filter scenarios

The following scenarios for filtering data vary for each action. For specific information about sort and filter options for individual actions, see their entries in Chapter 4, “XML API Reference,” on

page 41.

Filtering data that has a type field

You can filter out or display only entries with a combination of matching types. For example, the following filter displays only the types

filter-type=folder&filter-type=meeting

The following example shows all types except folder and meeting:

filter-out-type=folder&filter-out-type=meeting

If the type field allows a null value, you might want to filter out entries with null and non-null values. The following example shows only types that are

filter-type=null

The following example shows only types that are not null:

filter-out-type=null

folder and meeting:

null:

Filtering data based on the date of a record

The following example shows all records whose date modified is between July 1 and July 10:

filter-lt-date-modified=2004-07-10T10:00:00.000-07:00&filter-gt-date-

modified=2004-07-1T10:00:00.000-07:00

Special filter scenarios 23

Filtering a specific number of entries starting at a specific entry

You can use the following technique to create pagination when there is too much data for one page. The following example shows 25 records starting at the 100th record:

filter-rows=25&filter-start=100

Filtering by membership in standard groups

To filter by membership in standard groups, filter by the type field, as in the following example:

action=principal-list&filter-type=admins

Do not use the name field to filter by membership in standard groups because the group names can be changed and are therefore unreliable. For example, the following example shows an incorrect way to filter by group membership:

action=principal-list&filter-name=Account Administrators

Filter reference

Filters comprise a type (either filter or sort) with an optional modifier, the name of the field, if needed, and finally, the value of the field name, as the following example shows:

Type-Modifier-FieldName=Value

The following table lists all the filter types and modifiers that you can use with Breeze:

Type Modifier Description

filter (none)

filter like

filter out

filter rows

filter start

filter gt

filter lt

filter gte

filter lte

sort (none)

Field must match value exactly.

Field must contain value.

Field cannot contain value.

Limits the return result to number of rows specified in value. Does not use the field name.

Selects all items greater than the value. Works only with dates.

Selects all items greater than or equal to the value. Works only with dates.

Selects all items less than or equal to the value. Works only with dates.

Sorts results. Value must be asc or desc.

24 Chapter 2: Working with Filters

Testing code in the browser

You can enter a test URL in the address field of a browser window and see the XML response from the server. It is a good idea to become comfortable with filters in the browser before you write code.

There are many nuances to filters that determine which types of filters you can use with certain API calls. The browser approach lets you quickly try combinations to see what works and what doesn’t. If you try this outside the browser, you add the extra time of compiling, loading the result in your application server, and debugging to see if a filter works as you expect. Using a browser, on the other hand, is much faster and gives you immediate feedback.

For example, you could use the following URL and filter to find all courses with the word filter in the name and the word date in the course description. This sample URL uses

breezedev.mycompany.com as the server name. Make sure you log on to the server first, and

then enter the following URL, substituting your server name for

http://breezedev.mycompany.com/api/xml?action=report-my-courses&filter-like-

name=filter&filter-like-description=date

The result in the browser should look similar to the following:

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

<my-courses>

<name>Understanding Filters Part 2</name> <description>Second course in the series, covering important topics such

as date and range filtering.</description> <url>admin.ibreeze.macromedia.com/p40583853/</url> <date-created>2004-05-26T17:51:40.840-07:00</date-created> <date-modified>2004-05-26T17:51:47.750-07:00</date-modified> <date-begin>2004-05-24T14:00:00.000-07:00</date-begin> <url-path>/p40583853/</url-path> <expired>false</expired>

</course>

</my-courses>

</results>

If your filters are too stringent and no courses meet your criteria, the output looks like this:

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

<my-meetings />

</results>

Finally, as you experiment with filters and APIs in the browser, you might get an unexpected response. For example, if you enter the wrong filter field name, which matches some other item in the database, you could receive an XML response that starts with the following:

<?xml version="1.0" encoding="utf-8" ?> <results> <status code="internal-error">

breezedev.mycompany.com:

Testing code in the browser 25

To make your code production-ready, develop it to handle unexpected errors and situations. Make sure you check for unexpected status codes and inform your IT team when you encounter such a situation.

Where to go from here

The Macromedia Breeze Resource Center has an article called “Working with Filters” that describes how to build a sample application that uses filters to search and sort a list of courses. In the article, you learn how to use filters with Breeze web services by working through a simple example that retrieves the list of enrolled courses for a user and lets the user search and sort the list. It also explains the different ways that filters help you optimize retrieved data for use in other enterprise systems.

26 Chapter 2: Working with Filters

CHAPTER 3

Common Tasks

This chapter describes common scenarios for integrating Macromedia Breeze with external applications or systems. These scenarios show how to accomplish several common tasks. To perform each task, you call one or more APIs on the Breeze server and then parse the XML tags that the server returns. In some cases, you use returned information as parameter values for the next API.

This chapter also provides sample code demonstrating how to perform some of the tasks using Macromedia ColdFusion Markup Language (CFML).

Note: Not all the task descriptions include sample code. The syntax for calling an API is consistent for all APIs, so you can use the sample code from tasks that include it as models for code to perform other tasks.

For detailed information about each API and each XML tag, see Chapter 4, “XML API

Reference,” on page 41 and Chapter 5, “XML Results Reference,” on page 139. The following

tasks are covered in this chapter:

Calling your first API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Logging in to Breeze . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Creating a new user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Adding a user to a group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Creating a meeting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Creating a meeting from a template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Displaying a user’s meetings, courses, and events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Creating and managing learning paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Integrating Breeze with a directory service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Integrating Breeze with a portal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Generating reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Calling your first API

You can enter a test URL in the address field of a browser and see the XML response from the server displayed in the browser window. The returned XML is the same as the returned XML when you call the API in an application. You should be comfortable with calling APIs in the browser before you write code in an application.

To call most APIs, a user must be logged in to Breeze. (The APIs you can call without logging in are

action-list, common-info, login, and user-accounts.) A good first API to call is

action-list because a user doesn’t have to be logged in, and it returns a list of other APIs you

can call.

To call an API, you need to know the following:

• The domain of your breeze account.

For example,

breeze.yourcompany.com.

• The name of the API you want to call.

For a complete list of APIs, see “XML API Reference” on page 41.

To call a Breeze API in a browser:

Open a browser.

Enter the address of the Breeze server in the browser’s address bar. Append the action parameter in a query string:

http://breeze.example.com/api/xml?action=action_name

Press Enter (Windows) or Return (Macintosh).

The API returns its XML results in the browser window. For example, a call to the

API returns the following XML:

list

<action>accesskey-info</action> <action>account-contact-update</action> <action>acl-field-info</action> <action>acl-field-list</action> <action>acl-field-update</action> <action>acl-preference-update</action> <action>action-list</action> ... list of actions continues...

</actions>

</results>

You can also test filters in the browser. For more information, see “Testing code in the browser”

on page 25.

action-

28 Chapter 3: Common Tasks

Logging in to Breeze

To call most APIs, you must be acting as a logged-in user, so you must call the login API before you can call most other APIs. (The exceptions—APIs you can call without logging in—are

action-list, common-info, login, and user-accounts.)

When you call the includes a

loginCookie. Then pass the loginCookie variable as a session parameter in subsequent API

BREEZESESSION cookie. Capture the cookie and save the results to a variable, such as

calls.

To log in a user to Breeze:

Create a ColdFusion page with the following content:

<cfhttp url="#baseurl#/api/xml?action=report-my-

meetings&session=#loginCookie#" method="GET"/>

</cfif>

<form action="#CGI.Script_Name#" method="POST"> Username: <input type="text" name="username" size="25"><br> Password: <input type="password" name="password" size="25"><br>

</form> </cfif>

Save the page as login.cfm in the ColdFusion wwwroot directory.

View login.cfm in a browser (use a localhost URL).

Logging in to Breeze 29

Reviewing the code

The following table describes the highlighted code and its function:

Code Description

<cfset baseurl = "http://

breezeserveraddress">

<cfhttp url="#baseurl#/api/

xml?action=login&login=#FORM.username#& password=#FORM.password#" method="GET"/ >

<cfset loginHeader = CFHTTP.header> <cfset loginCookie =

ListLast(ListFirst(loginHeader, ";"), "=")>

<cfif

xml.XmlRoot.status.XMLAttributes['code' ] EQ "OK">

<cfhttp url="#baseurl#/api/

xml?action=report-mymeetings&session=#loginCookie#" method="GET"/>

<cfset meetings = CFHTTP.FileContent/

<cfset meetings_xml =

XMLParse(meetings)/>

</cfif>

Username: <input type="text" name="username" size="25"><br> Password: <input type="password" name="password" size="25"><br>

name="submit" value="Submit"><br> </form> </cfif>

<input type="submit"

Checks whether the username variable is defined. If it is, the next block of code executes. If it isn’t, a form is displayed that allows a user to provide a user name (and password).

If the username variable is defined, sets the baseurl variable to the name of the Breeze server. Uses the

baseurl variable in the <cfhttp> tag to call the login API on the Breeze server. The login API

requires two parameters, which a user enters into a form.

Dumps the data returned by the <cfhttp> call into the

response variable. The second line converts the

string data in the document object and stores it in the

Dumps the header information from the <cfhttp> call into the parses the header to pull out the value of the

BREEZESESSION cookie and store it in the loginCookie variable.

Checks whether the status code attribute in the XML response is

If the status code is ok, the login API call was successful and a user is logged in. You can now pass the parameter to act as the logged-in user and call any API. This code calls the report-my-meetings API, dumps the response into the converts the document object.

If the status code attribute in the login API’s XML response was not

If FORM.username is not defined, a form is displayed to gather a user name and password.

response variable into an XML

xml variable.

loginHeader variable. The second line

ok.

loginCookie variable as the session

meetings variable, and

meetings variable into an XML

ok, print Login Failed.

30 Chapter 3: Common Tasks

Creating a new user

To create a new user, call the principal-update API with the following parameters: first-

, last-name, login, password, has-children, and type (either user or group). The

name

following code creates a new user for the Breeze account located at

http://breezeserveraddress/api/xml?action=principal-update&first-

name=Will&last-name=Tip&login=wtip@macromedia.com&password=66Mustang&haschildren=0&type=user

breezeserveraddress:

Adding a user to a group

To add a user to a group, call the group-membership-update API.

To a add a user to a group using the XML API, do the following:

Create the new user (if the user has not been created yet). For example:

http://breezeserveraddress/api/xml?action=principal-update&first-

name=Will&last-name=Tip&login=wtip@macromedia.com&password=66Mustang&haschildren=0&type=user

Parse the returned XML for this new user or a current user and grab the value of principal-id.

Call group-membership-update and pass it the principal-id of the user you want to add to the group, as in the following example:

http://breezeserveraddress/api/xml?action=group-membership-update&group-

id=1222&principal-id=1822&is-member=true

Note the following:

■ Pass in the principal-id for the user you want to add to this group.

■ Get the group-id for the group you want the user to join and pass that in as the group-id

parameter.

■ Use the is-member parameter to add or remove a user: true adds the user and false

removes the user.

Displaying a user’s meetings, courses, and events

To display a user’s meetings and courses, call the report-my-meetings, report-my-courses, and

report-my-events APIs. You can use sort and filter the returned XML to limit your results.

For example, the following code lists a user’s meetings in ascending order based on their start date:

http://breezeserveraddress/api/xml?action=report-my-meetings&sort-date-

begin=asc&session=#loginCookie#

Note: For more information about the session parameter, see Logging in to Breeze.

Displaying a user’s meetings, courses, and events 31

Creating a meeting

To create a meeting room, you must have appropriate permissions. When using the XML API, you should create an administrator account with Account Administrator privileges to perform administrator functions on a Breeze account.

To create a meeting, call the

sco-update API while logged in to the administrator account. The

following code creates a meeting:

http://breezeserveraddress/api/xml?action=sco-update&folder-id=15&date-

begin=2005-01-01T01:00:00.000-05:00&date-end=2005-01-02T01:00:00.00005:00&description=2005-D003&name=Test%20Meeting&type=meeting

Creating a meeting from a template

Templates are simply meetings in a folder. For example, to list available templates, call the sco-

shortcuts

following code calls the API:

http://

The following code is a sample of the returned XML:

</shortcuts>

</results>

After finding the shortcut of type my-meeting-templates, call the sco-contents API, and pass the following API lists all available templates:

http://

To set the template when you create a SCO (meeting), call add the following parameter:

source-sco-id=sco id of your template

Note: This only works when you create the meeting. After that, the value of source-sco-id doesn’t matter because Breeze won’t set the template.

API, and grab the sco-id of the folder you want from the returned XML. The

breezeserveraddress/api/xml?action=sco-shortcuts

<domain-name>http://admin.breeze.example.com</domain-name> </sco> <sco tree-id="181230" sco-id="181577" type="my-meeting-templates">

<domain-name>http://admin.breeze.example.com</domain-name> </sco> <sco tree-id="181227" sco-id="181412" type="my-content">

<domain-name>http://admin.breeze.example.com</domain-name> </sco> <sco tree-id="181225" sco-id="181225" type="content">

<domain-name>http://admin.breeze.example.com</domain-name> </sco> <sco tree-id="181226" sco-id="181226" type="courses">

<domain-name>http://admin.breeze.example.com</domain-name> </sco>

my-meeting-templates as the sco-id parameter. The XML returned from a call to the

breezeserveraddress/api/xml?action=sco-contents&sco-id=181577

sco-update to create the SCO, and

32 Chapter 3: Common Tasks

Creating and managing learning paths

To create and manage learning paths, use the following APIs: learning-path-info, learning-

path-update

, and user-transcript-update. Call learning-path-info to discover the restrictions on a particular learning object that create the learning path (for example, which learning objects must be completed, if any, before the next learning object is attempted). Call

learning-path-update to modify the learning path by changing the prerequisite or

preassessment requirements for a particular learning object.

Integrating Breeze with a directory service

Suppose your organization uses a central repository of user information, such as Lightweight Directory Access Protocol (LDAP). Breeze lets you import or synchronize user information from such a directory service.

The following procedure describes the steps that your application should follow to perform this task. This procedure assumes that if the information provided by the directory service doesn’t match the information provided by the Breeze server, the information from the directory service is correct and up-to-date.

To synchronize Breeze with the directory service:

Log in by calling the login API on the Breeze server, specifying the login name and password of an account administrator. Examine the returned HTTP headers to find the value of the

BREEZESESSION cookie, which you need when calling subsequent APIs.

Note: Consider creating an administrative user specifically for performing synchronizations. If you create such a user, you should exclude it from the list of users to synchronize when you perform the synchronization.

The following code example logs in a user and obtains the cookie value:

<cfset params="action=login&login=#login#&password=

#password#">

<cfset fullCookie= mid(c, len(cookieName)+2,

len(c)-len(cookieName)+1) />

</cfif>

</cfloop>

</cfif>

</cfloop>

Integrating Breeze with a directory service 33

Check that the login API completed successfully by parsing the returned XML and examining the value of the

If the status code isn’t

status tag’s code attribute.

ok, determine what the error was and handle it appropriately, as in the

following:

</cfif>

Request a list of Breeze users from the Breeze server by calling the principal-list API.

The server returns a complete list of all principals, including principals that aren’t users. (For information about principals, see “About principals, SCOs, and IDs” on page 17.)

The following code calls the

principal-list API. The cookie value from the previous step is

included as an HTTP parameter.

</cfhttp>

Note: This HTTP request uses the POST an HTTP parameter in CFML is by using POST. The URL and the query parameters remain the same as if you were using GET, however.

Make sure that the API completed successfully by parsing the returned XML to ensure that the value of the

status tag’s code attribute is set to ok.

If your code must be robust, you should check the

method rather than GET because the only way to specify

status tag in the returned XML after every

API.

If the status code is ok, search the returned list of principals to find all principals that have a

type attribute set to user.

The following example places a list of all Breeze users into the array

Obtain a list of all the users listed in the directory service.

allUsers:

The procedure for obtaining this list depends on the directory service.

Compare the values contained in the login tags for the Breeze users with the e-mail addresses from the directory service, using a list-comparison algorithm of your choice.

Determine which users are in the directory service but not in Breeze; these are new users to be added to Breeze.

Determine which users are in Breeze but not in the directory service; these users should be removed from Breeze.

Determine which users are in both Breeze and the directory service, but have different names in the two places; these users’ names should be changed in Breeze.

34 Chapter 3: Common Tasks

For each user listed in the directory service but not in Breeze, add the user to Breeze, as follows:

Obtain the user’s first name, last name, and login name from the directory service.

The Breeze login name is usually the user’s e-mail address.

Call the principal-update API, setting the type parameter equal to user.

Don’t specify a

principal-id parameter; leaving out principal-id indicates that you are

adding a new user rather than updating an existing user.

Check the returned XML to ensure that the status code returned is ok.

The following code demonstrates how to add a user to Breeze. It uses variables set up in previous steps of this procedure, such as

baseurl. To keep the example clear and simple, this

code specifies the user’s information in the first few lines, rather than acquiring that information from a directory service.

<cfset newlogin= "jake2@example.com"> <cfset newpass= "abcdefg"> <cfset newfirst= "Jake"> <cfset newlast= "Doe"> <cfhttp url="#baseurl#api/xml?

action=principal-update&first-name=#newfirst# &last-name=#newlast#&has-children=0&login=#newlogin# &type=user" method="post">

<!--- No status code "ok" found. Check for other status codes and handle

errors. ---> </cfif>

For each user listed in Breeze but not in the directory service, delete the user from Breeze by calling the

10.

For each deleted user, check the returned XML to ensure that the status code returned is ok.

principals-delete API and specifying the user’s ID.

The following code demonstrates how to delete a specified user:

<cfset userID= "503123"> <cfhttp url="#baseurl#api/xml?

action=principals-delete&principal-id=#userID#" method="post">

<!--- No status code "ok" found. Check for other status codes and handle

errors. ---> </cfif>

Integrating Breeze with a directory service 35

11.

For each user whose information in Breeze must be updated, obtain the user’s ID, as follows:

Examine the data returned by the principal-list API in steps 2 through 4 and search for

the ID associated with the user’s login.

Obtain the user’s old first name and last name by calling the principal-info API.

Change the values as needed to match the name given by the directory service.

Call the principal-update API.

Check the returned XML to ensure the status code returned is ok.

The following code doesn’t include code for calling

principal-update or checking the

status code because those procedures were described in earlier steps:

<cfset principal= XmlSearch(xmlPrincipalList,

"//principal[login='#login#']")>

<cfhttp url="#baseurl#api/xml?

action=principal-info&principal-id=#principalId# " method="post">

<cfhttpparam type="Cookie" name="BREEZESESSION" value="#loginCookie#"> </cfhttp> ...  ... <cfset xml= XmlParse(cfhttp.FileContent)> <cfset firstElement= XmlSearch(xml, "results/contact/first-name")> <cfset firstName= firstElement[1].XmlText> <cfset lastElement= XmlSearch(xml, "results/contact/last-name")> <cfset lastName= lastElement[1].XmlText> ... <!--- Add code here to set the new values for first name and last name,

call principal-update, and check for an "ok" status code. --->

Integrating Breeze with a portal

Suppose you have a portal application, such as a company’s intranet portal. You can integrate Breeze into the portal to let users view and modify Breeze-related information from within the context of the portal. For example, users can view upcoming Breeze meetings and see which courses they are enrolled in.

The procedures in this section describe how to perform various tasks for a portal application integrated with Breeze.

To log in as a particular user:

Obtain the user’s login name and password, using a web-based form.

Call the login API on the Breeze server, using the specified login name and password.

Check the returned XML to ensure the status code returned is ok.

If the status code is need to capture that cookie to use in subsequent API calls.

36 Chapter 3: Common Tasks

ok, the response header includes a cookie called BREEZESESSION. You

To determine a user’s ID, given their login name and password:

Call the common-info API.

Parse the returned XML to find the value of the user-id attribute of the user tag.

That value is the user’s ID.

To check whether an entered password is correct:

If the status code returned is ok, the password is correct.

This procedure is the only way to check a password; for security reasons, Breeze doesn’t let you request a user’s password from the server.

To list all the courses the user is enrolled in:

Call the report-my-courses API.

Parse the returned XML and display the results.

For more information about the returned XML, see

Note: The BREEZESESSION cookie must be supplied with this request. For more information, see

“Logging in to Breeze” on page 29.

To list all the meetings the user has signed up to attend:

Call the report-my-meetings API.

Parse the returned XML and display the results.

For more information about the returned XML, see

my-courses on page 170.

my-meetings on page 171.

To display the contents of the user’s content folder:

Call the sco-shortcuts API.

This API provides the location of the root folder of the current account as well as the locations of other folders, such as the current user’s meetings and other content.

The following code uses the same

baseurl and loginCookie variables that are set in the login

code in “Integrating Breeze with a directory service” on page 33:

</cfhttp>

Determine the ID of the My Content folder by searching for the appropriate type attribute in the returned

sco tags:

Integrating Breeze with a portal 37

If you want to provide links to content items in the form of absolute URLs, determine the domain name of the folder:

<cfset domainElement= XmlSearch(xml,

"//sco[@tree-id='#myTreeId#']/domain-name")>

Call the sco-contents API, using the folder’s SCO ID.

The following API provides a list of the contents of the specified folder:

<cfhttp url="#baseurl#api/xml?

action=sco-contents&sco-id=#contentSco#" method="post"> <cfhttpparam type="Cookie" name="BREEZESESSION" value="#loginCookie#">

</cfhttp>

Parse the returned XML and display relevant information to the user:

</tr> <cfloop index="i" from="1" to="#contentCount#">

<td>#item.XmlAttributes["sco-id"]#</td>

<td>#item.name.XmlText#</td>

<td>#item.XmlAttributes["type"]#</td> </tr>

</cfloop> </table> </cfoutput>

To provide links to launch content items, call the sco-info API for each item, and determine the item’s full absolute URL by appending the returned

url-path tag to the domain name you

acquired.

This results in a URL such as http://breeze.example.com/p12345678/.

For more information about launching content, see “About security and launching content”

on page 19.

To create a new meeting:

(Optional) Let the user determine the ID of the folder in which to create the new meeting, using a web-based interface. If you don’t specify a folder, the meeting is created in the my-meetings folder. You can determine the ID of the my-meetings folder by calling the

38 Chapter 3: Common Tasks

sco-shortcuts API.

Call the sco-update API, using the folder’s ID for the folder-id parameter. Don’t specify a

sco-id parameter.

Verify that the API completed successfully by checking the returned status tag.

To search for content:

Obtain the string to search for from the user, using a web-based form.

Call the sco-search API, using the specified string as the value of the query parameter.

Parse the returned XML to find information about the SCOs that contain the string; display the relevant information to the user.

Generating reports

Suppose you want your application to provide information about all the courses a user is registered for or to identify the users who registered for a given meeting. The Breeze XML web services include a variety of reports, each of which provides data on Breeze use.

Report data is returned in XML form. You can use the results in your system, such as a web application, or you can convert the data into other file formats, such as comma separated value (CSV) files.

To generate a learner status report as a CSV file:

Call the sco-contents API to determine the ID of a course.

Call the report-quiz-takers API.

This API returns a set of for the course.

Parse the XML and write the data as text, with commas separating the fields, to a CSV file.

The most common approach shows the resulting CSV file as text in the user’s browser, which lets the user save the file to their local disk.

You can use a server language such as CFML to translate the file to CSV, or you can use a transformation language such as XSL Transformations (XSLT). For information about XSLT, see “Additional resources” on page 11.

row tags, each providing information about a user who is signed up

Generating reports 39

40 Chapter 3: Common Tasks

CHAPTER 4

XML API Reference

This chapter provides reference material for each application programming interface (API) that is exposed in the Macromedia Breeze XML API, including information about the parameters that you can pass with each API. The APIs are listed in alphabetical order.

Every API returns a The “Returned elements” section of the documentation for each API lists only the other elements returned;

For information about the XML tags, data, and status codes returned by the Breeze server, see

Chapter 5, “XML Results Reference,” on page 139.

For examples of how to perform various common tasks, see Chapter 3, “Common Tasks,” on

page 27.

For information about specifying parameters, see “About parameters” on page 16. For information about principals and Shareable Content Objects (SCOs), see “About principals,

SCOs, and IDs” on page 17.

results and status are assumed.

results tag that contains one or more other tags, including a status tag.

Sample API entry

The following sample entry explains the conventions that are used for all XML APIs. Entries are listed alphabetically.

Entry title

This is the heading that names the API.

Availability

Unless otherwise noted, this section tells which versions of Breeze support the API. An API is supported by the specified version and all later versions, unless otherwise indicated.

Description

This section describes how to use the API.

Parameters

This section describes any parameters listed in the syntax. All parameters are required unless they are marked “optional.”

Filters

This section describes fields on which you can filter and sort the returned XML data.

Returned elements

This section identifies what, if any, XML elements the API returns.

Sample results

This section provides a code sample that demonstrates how to use the API.

See also

This section identifies APIs that are related to the API.

API listing by function

The following tables group the XML APIs according to function.

Content and meeting management

You can use the Breeze web services to create and manage Breeze assets and meetings (SCOs) from any application, such as an external portal, that consumes web services. For example, you can upload content from an external portal application into Breeze. You can also create new meeting or collaboration sessions from a portal application.

The following table lists the content and meeting management APIs supported in Breeze 5:

API Description

sco-build Causes the Breeze server to build the specified SCO when

you create presentations with the XML API.

sco-contents Provides a list of the SCOs in a specified folder.

sco-delete Deletes one or more SCOs.

sco-expanded-contents Lists all of the SCOs in a folder.

sco-info Provides information about a SCO.

sco-move Moves a SCO from one folder to another.

sco-nav Describes the folder hierarchy that contains the specified

SCO.

sco-search Provides a list of all SCOs that match the search text.

sco-shortcuts Provides IDs for a set of folders that contain content relevant

to the logged-in user: a folder where the user can place meetings, a folder where the user can place content, and so on.

42 Chapter 4: XML API Reference

API Description

sco-update Creates or updates presentations, courses, and meetings.

sco-upload Uploads a file to the Breeze server when you create a

presentation with the XML API. (For more information, see

sco-update and sco-build).

Curriculum and learning path management

You can use the Breeze web services to create and manage learning paths associated with a curriculum and a user.

The following table lists the curriculum APIs supported in Breeze 5:

API Description

learning-path-info Returns a list of learning paths for a learning object that

belongs to a curriculum.

learning-path-update Updates the learning path for a single learning object in a

user-transcript-update Resets a user's transcript for a learning object or marks it as

curriculum.

complete.

Custom fields

You can use custom fields to add fields to Breeze objects. The following table lists the custom fields APIs supported in Breeze 5:

API Description

acl-field-info Returns field-ids and values for an ACL.

acl-field-list Returns the list of acl-ids and values in the logged-in account

for the given field-id.

acl-field-update Updates the field value for the given ACL and field.

acl-preference-update Updates the user profile to the specified language and time

zone settings.

custom-fields-delete Deletes the specified account custom field.

General

The following table lists the general APIs supported in Breeze 5.:

API Description

action-list Returns a list of Breeze web service APIs.

common-info Provides basic information about the current user and server.

API listing by function 43

API Description

logout Logs out a user, invalidating the cookie that the application

received when the user logged in.

Permissions

The following table lists the permissions APIs supported in Breeze 5:

API Description

permissions-info Provides information about principals and the permissions

they have for a specified SCO.

permissions-reset Resets all principals’ permissions for the specified SCO, so

permissions-update Updates one or more principal’s permissions for one or more

that the permissions of the SCO’s parent apply to all principals.

SCOs.

Reports

You can use the detailed reporting capabilities of the Breeze web services in external systems such as employee performance management solutions. The following Breeze web service APIs allow you to integrate the Breeze reporting repository with external systems for real-time reporting that uses a single reporting infrastructure.

The following table lists the reports APIs supported in Breeze 5:

API Description

report-active-meeting-presenters Provides a list of the users who are currently presenting

meetings.

report-active-meetings Provides a list of meetings that are currently in progress.

report-bulk-consolidatedtransactions

report-bulk-objects Returns information about every object on the Breeze server.

report-bulk-questions Returns information about every quiz question in a particular

report-bulk-slide-views Returns information about every instance of a principal

report-bulk-users Returns information about all the users in an account.

report-course-status Returns course status for either a principal or a SCO, based

44 Chapter 4: XML API Reference

Returns information about all the transactions in an account. A transaction is an instance of one principal visiting one SCO.

Object types include archive, attachment, authorware, captivate, course, curriculum, external-event, FLV, image, meeting, presentation, and SWF.

account.

viewing a slide in an account.

on the parameters passed in.

API Description

report-meeting-attendance Provides a list of users who have attended the specified

meeting.

report-meeting-concurrent-users Indicates the maximum number of users who can participate

simultaneously in the specified meeting.

report-meeting-sessions Provides information about all the sessions of a meeting.

report-meeting-summary Indicates how many users were invited to the specified

meeting and how many invitees and guests attended.

report-my-courses Provides information about each course in which the logged-

in user is enrolled.

report-my-events Provides information about each event the logged-in user is

scheduled to attend.

report-my-meetings Provides information about each meeting the logged-in user

is scheduled to attend.

report-quiz-interactions Provides information about all the interactions that users have

had with the specified quiz.

report-quiz-question-answerdistribution

report-quiz-question-distribution Indicates how many users answered each question in the

Indicates how many users selected a specific answer for all questions on a quiz associated with the specified SCO.

specified quiz correctly.

report-quiz-question-response Provides a list of all answers that users have given to a

particular quiz question.

report-quiz-question-totals For the specified quiz question, indicates the total number of

users who answered the question and the number of users who answered the question correctly.

report-quiz-summary Provides information about the results of a quiz.

report-quiz-takers Provides information about everyone who has taken a

particular quiz.

report-quotas Returns information about the account quotas.

report-sco-slides Indicates how many times, and how recently, each slide in a

presentation has been viewed.

report-sco-views Indicates how many times, and how recently, the specified

presentation has been viewed.

User management

Breeze provides a complete set of web services that allow you to develop synchronization processes between your directory service and Breeze. Additionally, these web services allow you to integrate user profiles, personalized Breeze content, and reporting data in external systems such as portal, CRM, and ERP applications.

API listing by function 45

The following table lists the user management APIs supported in Breeze 5:

API Description

group-membership-update Adds one or more principals to a group, or removes one or

more principals from a group.

principal-info Provides information about the specified principal. The

specified principal can be a user or a group.

principal-list Provides a complete list of users and groups, including

primary groups.

principal-list-by-field Allows you to list principals that have a given field value.

principal-update Updates information for a principal in the current account or

creates a new principal.

principals-delete Deletes one or more principals.

user-accounts Provides a list of the accounts to which the specified user

belongs.

user-update-pwd Changes a user’s password.

Alphabetical API listing

The following list contains all of the APIs that are documented in this reference chapter. APIs that Breeze 5 does not support are indicated in the Description column.

API Description

accesskey-exec Executes special functions associated with special access

keys. This API is not supported in Breeze 5.

accesskey-info Provides a special access key, if such a key is associated with

acl-field-info Returns field-ids and values for an ACL.

acl-field-list Returns the list of acl-ids and values in the logged-in account

acl-field-update Updates the field value for the given ACL and field.

acl-preference-update Updates the user profile to the specified language and time

action-list Returns a list of Breeze web service APIs.

common-info Provides basic information about the current user and server.

custom-field-update Updates the specified account custom field. Creates a new

custom-fields Lists the custom fields of an account and the details of the

custom-fields-delete Deletes the specified account custom field.

the specified SCO. This API is not supported in Breeze 5

for the given field-id.

zone settings.

custom field if none exists. This API is not supported in Breeze 5.

fields. This API is not supported in Breeze 5.

46 Chapter 4: XML API Reference

API Description

group-membership-update Adds one or more principals to a group, or removes one or

more principals from a group.

learning-path-info Returns a list of learning paths for a learning object that

belongs to a curriculum.

learning-path-update Updates the learning path for a single learning object in a

curriculum.

logout Logs out a user, invalidating the cookie that the application

received when the user logged in.

permissions-info Provides information about principals and the permissions

they have for a specified SCO.

permissions-reset Resets all principals’ permissions for the specified SCO, so

that the permissions of the SCO’s parent apply to all principals.

permissions-update Updates one or more principals’ permissions for one or more

SCOs.

principal-info Provides information about the specified principal. The

specified principal can be a user or a group.

principal-list Provides a complete list of users and groups, including

primary groups.

principal-list-by-field Allows you to list principals that have a given field value.

principal-update Updates information for a principal in the current account or

creates a new principal.

principals-delete Deletes one or more principals.

report-account-meeting-attendance Returns the meeting attendance log for the account. This API

is not supported in Breeze 5

report-active-meeting-presenters Provides a list of the users who are currently presenting

meetings.

report-active-meetings Provides a list of meetings that are currently in progress.

report-bandwidth Indicates the total bandwidth consumed in the current

account since the account was created, in bytes. This API is not supported in Breeze 5.

report-bulk-consolidatedtransactions

report-bulk-content-quiz Returns information about all content quizzes, including a list

Returns information about all the transactions in an account. A transaction is an instance of one principal visiting one SCO.

of quizzes, and the questions and answers for each quiz. This API is not supported in Breeze 5.

report-bulk-content-quiz-results Returns results for a content quiz, including information on

each user and quiz question. This API is not supported in Breeze 5.

Alphabetical API listing 47

API Description

report-bulk-content-slide-views Returns slide view data for content. This API is not supported

in Breeze 5.

report-bulk-course-quiz Returns information about all course quizzes, including a list

of quizzes, and the questions and answers for each quiz. This API is not supported in Breeze 5.

report-bulk-course-results Returns results for a course quiz, including information about

each user and quiz question. This API is not supported in Breeze 5.

report-bulk-meeting Returns information about all meetings. This API is not

supported in Breeze 5.

report-bulk-meeting-attendance Returns meeting attendance data. This API is not supported

in Breeze 5.

report-bulk-objects Returns information about every object on the Breeze server.

Object types include archive, attachment, authorware, captivate, course, curriculum, external-event, FLV, image, meeting, presentation, and SWF.

report-bulk-questions Returns information about every quiz question in a particular

account.

report-bulk-slide-views Returns information about every instance of a principal

viewing a slide in an account.

report-bulk-users Returns information about all users in an account.

report-course-status Returns course status for either a principal or a SCO, based

on the parameters passed in.

report-course-takers Provides a list of the users enrolled in the specified course.

This API is not supported in Breeze 5.

report-disk-usage Provides information about how much hard disk space the

Breeze content for the current account uses, in bytes. This API is not supported in Breeze 5.

report-meeting-attendance Provides a list of users who have attended the specified

meeting.

report-meeting-concurrent-users Indicates the maximum number of users who can participate

simultaneously in the specified meeting.

report-meeting-session Provides information about a specific meeting session, such

as the session name, session starting and ending times, and the number of participants and guests who attended the session. This API is not supported in Breeze 5.

report-meeting-sessions Provides information about all the sessions of a meeting.

report-meeting-session-slots Provides information about the number of attendees in every

ten-minute time slot of the specified meeting session. This API is not supported in Breeze 5.

report-meeting-summary Indicates how many users were invited to the specified

meeting and how many invitees and guests attended.

48 Chapter 4: XML API Reference

API Description

report-my-courses Provides information about each course in which the logged-

in user is enrolled.

report-my-events Provides information about each event that the logged-in

user is scheduled to attend.

report-my-meetings Provides information about each meeting that the logged-in

user is scheduled to attend.

report-principal-list Returns the list of all principals in the account. This API is not

supported in Breeze 5.

report-quiz-answer-distribution Indicates how many users selected a specific answer for all

questions on a quiz associated with the specified SCO. This API is not supported in Breeze 5.

report-quiz-definition-answers Provides information about each of the allowed answers

(both correct and incorrect) for the specified quiz. This API is not supported in Breeze 5.

report-quiz-definition-questions Provides information about each question in a quiz. This API

is not supported in Breeze 5.

report-quiz-interactions Provides information about all the interactions that users have

had with the specified quiz.

report-quiz-question-answerdistribution

report-quiz-question-distribution Indicates how many users answered each question in the

Indicates how many users selected a specific answer for all questions on a quiz associated with the specified SCO.

specified quiz correctly.

report-quiz-question-response Provides a list of all answers that users have given to a

particular quiz question.

report-quiz-question-totals Indicates, for the specified quiz question, the total number of

users who answered the question and the number of users who answered the question correctly.

report-quiz-summary Provides information about the results of a quiz.

report-quiz-takers Provides information about everyone who has taken a

particular quiz.

report-quotas Returns information about the account quotas.

report-sco-slides Indicates how many times, and how recently, each slide in a

presentation has been viewed.

report-sco-views Indicates how many times, and how recently, the specified

presentation has been viewed.

report-survey-question-response Returns the list of all users who answered the specified

question and their answer. This API is not supported in Breeze 5.

sco-build Causes the Breeze server to build the specified SCO when

you create presentations with the XML API.

sco-contents Provides a list of the SCOs in a specified folder.

Alphabetical API listing 49

API Description

sco-delete Deletes one or more SCOs.

sco-expanded-contents Lists all of the SCOs in an account. Call this API with filters to

find particular SCOs.

sco-info Provides information about a SCO.

sco-move Moves a SCO from one folder to another.

sco-nav Describes the folder hierarchy that contains the specified

SCO.

sco-search Provides a list of all SCOs that match the search text.

sco-shortcuts Provides IDs for a set of folders that contain content relevant

to the logged-in user: a folder for the user to place meetings, a folder for the user to place content, and so on.

sco-update Creates or updates presentations, courses, and meetings.

sco-upload Uploads a file to the Breeze server when creating a

user-accounts Provides a list of the accounts to which the specified user

user-transcript-update Resets a user's transcript for a learning object or marks it as

user-update-pwd Changes a user’s password.

presentation using the XML API. (For more information, see

sco-update and sco-build).

belongs.

complete.

API reference entries

The following section lists the Breeze XML APIs alphabetically

accesskey-exec

Availability

Breeze 4. This API is not supported in Breeze 5.

Note: An updated API is not available because the self-registration feature no longer exists in Breeze 5.

Description

Executes special functions associated with special access keys.

You can call this API to do the following:

• Allow users to self-register for meetings and courses

• Create a new user

50 Chapter 4: XML API Reference

To c a l l t h e accesskey-exec API, you need a special access key associated with a meeting or course. Someone who isn’t a Breeze user can be given the special access key and can then use an interface to register for the meeting or course, creating a Breeze user account in the process. To obtain the special access key, call

accesskey-info. This API automatically adds the self-

registering user to the self-registration group associated with the course or meeting, if the group exists.

The difference between using that you can call

accesskey-exec without being logged in or being an administrator. Also, you

can specify custom fields for new users when you call fields to

accesskey-exec as additional parameters in name and value pairs, as shown in the

accesskey-exec and principal-update to create a new user is

accesskey-exec. To do so, pass the custom

following example:

field-id=xx&value=xxx&customfield-id=xx&value=xxx

The field-id parameters can be determined from the data returned by the custom-fields API.

Parameters

access-key

first-name The new user’s first name.

has-children Always set this parameter to 0 when registering a new user.

last-name The new user’s last name.

password The new user’s password.

type Always set this parameter to user when registering a new user.

The special access key that lets the user self-register.

Filters

Results cannot be filtered or sorted.

Returned elements

None.

Sample results

</results>

accesskey-info

Availability

Breeze 4. This API is not supported in Breeze 5.

Note: The accesskey feature no longer exists in Breeze 5, so there is no updated API.

Description

Provides a special access key, if such a key is associated with the specified SCO. For more information, see the

accesskey-exec API.

accesskey-info 51

To find out which group the user will automatically join by self-registering using the special access key, look in the the returned XML. If the group does not exist, there is no additional

access-key-group XML element. If the group exists, this element is included in

access-key-group

element.

Parameters

acl-id

The ID of a SCO.

Filters

Results cannot be filtered or sorted.

Returned elements

access-keys

Sample results

, access-key-group

The following sample XML is returned when a group doesn’t exist and therefore does not include an

access-key-group element:

<access-key acl-id="622847" action="action-self-reg-meeting"

parent-acl-id="503265"> <access-key>3hzvnifcfmphn3id</access-key> <date-created>2004-03-05T10:28:14.750-08:00</date-created>

</access-key>

</access-keys>

</results>

The following sample results are returned when a group exists and therefore includes an

accesskey-group element:

<login>COURSE-test1-self-reg-group</login>

<name>COURSE-test1-self-reg-group</name> </access-key-group> <access-keys>

<access-key acl-id="126" action="action-self-reg-course" parent-aclid="630">

<access-key>2cw6np2kx2dtdop2</access-key>

<date-created>2004-07-07T12:27:04.590-07:00</date-created>

</access-key> </access-keys>

</results>

52 Chapter 4: XML API Reference

acl-field-info

Availability

Breeze 5.

Description

Returns field-ids and values for an ACL. The caller must have view permission for the ACL. You can call

An ACL is a securable Breeze object, for example, a principal, SCO, or account. For more information, see “About principals, SCOs, and IDs” on page 17.

Parameters

acl-id

sco-id, an account-id, or a principal-id.

Filters

Results cannot be filtered or sorted.

Returned elements

acl-fields

Sample results

The following sample results were returned when the acl-id parameter was an account-id. Some fields in the account ACL list the main account contact; in this case, Mike Brown. The other fields identify the company associated with the account. The fields are specified at account creation time and stored in an ACL field.

com.macromedia.breeze_ext.premiere.gateway.PTekGateway

principal-list to determine the account-id or principal-ids.

The ID of the ACL whose field information you want to return. This parameter can be

<value>dblack@macromedia.com</value> </field> <field acl-id="38181499" field-id="first-name">

<value>Daryl</value> </field> <field acl-id="38181499" field-id="last-name">

<value>Black</value> </field> <field acl-id="38181499" field-id="account-company">

<value>Macromedia</value> </field> <field acl-id="38181499" field-id="telephony-adaptor">

<value>

</value> </field> <field acl-id="38181499" field-id="pricing-model-training">

<value>concurrent-learner</value> </field>

acl-field-info 53

<value>concurrent-attendee</value> </field>

</acl-fields>

</results>

See also

acl-field-list

, acl-field-update

acl-field-list

Availability

Breeze 5.

Description

Returns the list of acl-ids and values in the logged-in account for the given field-id. For example, to list the first names of all users in an account, call this API with

. This API requires Administrator permission on the logged-in account.

name

Call

acl-field-info to determine the possible fields for an ACL.

An ACL is a securable Breeze object, for example, a principal, SCO, or account. For more information, see “About principals, SCOs, and IDs” on page 17.

Parameters

field-id

The ID of the field whose values you want to list.

field-id=first-

Filters

Results cannot be filtered or sorted.

Returned elements

acl-field-list

Sample results

<value>Stephanie</value> </acl> <acl acl-id="38130237">

<value>Daryl</value> </acl> <acl acl-id="38140560">

</acl-field-list>

</results>

See also

acl-field-info

54 Chapter 4: XML API Reference

, acl-field-update

acl-field-update

Availability

Breeze 5.

Description

Updates the field value for the given ACL and field. The caller requires modify permission on the ACL.

An ACL is a securable Breeze object, for example, a principal, SCO, or account. For more information, see “About principals, SCOs, and IDs” on page 17.

Parameters

acl-id

The ID of the ACL that you want to modify. This can be a principal-id, sco-id, or

account-id.

field-id The ID of the field that you want to edit.

value The value that you want to set for the field specified by the field-id parameter.

Filters

Results cannot be sorted or filtered.

Returned elements

None.

Sample results

The following call updates the first name of the user with ACL ID 38140560 (call acl-field-

to determine the ACL ID):

list

http://server_name/api/xml?action=acl-field-update&acl-id=38140560&field-

id=first-name&value=Mary%20Sue

The results are as follows:

</results>

Now call acl-field-list again to see the updated first name:

http://server_name/api/xml?action=acl-field-list&field-id=first-name

The results are as follows:

<acl-field-list>

<value>Stephanie</value> </acl> <acl acl-id="38130237">

acl-field-update 55

</acl-field-list>

</results>

See also

acl-field-list

, acl-field-info

acl-preference-update

Availability

Breeze 4.

Description

Updates the user profile to the specified language and time zone settings.

Parameters

acl-id

The ID of the user for whom the preferences need to be updated.

lang The language setting. Breeze currently supports the following five languages:

Language Parameter value

English

French

German

Japanese

Korean

time-zone-id The time zone setting. Breeze currently supports the following 75 time zones:

Time zone setting Parameter value

(GMT-12:00) International Date Line West

(GMT-11:00) Midway Island, Samoa

(GMT-10:00) Hawaii

(GMT-09:00) Alaska

(GMT-08:00) Pacific Time (US and Canada); Tijuana

(GMT-07:00) Mountain Time (US and Canada)

(GMT-07:00) Chihuahua, La Paz, Mazatlan

(GMT-07:00) Arizona

(GMT-06:00) Central Time (US and Canada)

(GMT-06:00) Saskatchewan

56 Chapter 4: XML API Reference

Time zone setting Parameter value

(GMT-06:00) Guadalajara, Mexico City, Monterrey

(GMT-06:00) Central America

(GMT-05:00) Eastern Time (US and Canada)

(GMT-05:00) Indiana (East)

(GMT-05:00) Bogota, Lima, Quito

(GMT-04:00) Atlantic Time (Canada)

(GMT-04:00) Caracas, La Paz

(GMT-04:00) Santiago

(GMT-03:30) Newfoundland

(GMT-03:00) Brasilia

(GMT-03:00) Buenos Aires, Georgetown

(GMT-03:00) Greenland

(GMT-02:00) Mid-Atlantic

(GMT-01:00) Azores

(GMT-01:00) Cape Verde Islands

(GMT) Greenwich Mean Time: Dublin, Edinburgh, Lisbon, London

(GMT) Casablanca, Monrovia

(GMT+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague

(GMT+01:00) Sarajevo, Skopje, Warsaw, Zagreb

(GMT+01:00) Brussels, Copenhagen, Madrid, Paris

(GMT+01:00) Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna

(GMT+01:00) West Central Africa

(GMT+02:00) Bucharest

(GMT+02:00) Cairo

(GMT+02:00) Helsinki, Kiev, Riga, Sofia, Tallinn, Vilnius

(GMT+02:00) Athens, Istanbul, Minsk

(GMT+02:00) Jerusalem

(GMT+02:00) Harare, Pretoria

(GMT+03:00) Moscow, St. Petersburg, Volgograd

(GMT+03:00) Kuwait, Riyadh

(GMT+03:00) Nairobi

(GMT+03:00) Baghdad

(GMT+03:30) Tehran

100

105

110

113

115

120

125

130

135

140

145

150

155

158

160

acl-preference-update 57

Time zone setting Parameter value

(GMT+04:00) Abu Dhabi, Muscat

(GMT+04:00) Baku, Tbilisi, Yerevan

(GMT+04:30) Kabul

(GMT+05:00) Ekaterinburg

(GMT+05:00) Islamabad, Karachi, Tashkent

(GMT+05:30) Chennai, Kolkata, Mumbai, New Delhi

(GMT+05:45) Kathmandu

(GMT+06:00) Astana, Dhaka

(GMT+06:00) Sri Jayawardenepura

(GMT+06:00) Almaty, Novosibirsk

(GMT+06:30) Rangoon

(GMT+07:00) Bangkok, Hanoi, Jakarta

(GMT+07:00) Krasnoyarsk

(GMT+08:00) Beijing, Chongqing, Hong Kong SAR, Urumqi

(GMT+08:00) Kuala Lumpur, Singapore

(GMT+08:00) Taipei

(GMT+08:00) Perth

(GMT+08:00) Irkutsk, Ulaan Bataar

(GMT+09:00) Seoul

(GMT+09:00) Osaka, Sapporo, Tokyo

(GMT+09:00) Yakutsk

(GMT+09:30) Darwin

(GMT+09:30) Adelaide

(GMT+10:00) Canberra, Melbourne, Sydney

(GMT+10:00) Brisbane

(GMT+10:00) Hobart

(GMT+10:00) Vladivostok

(GMT+10:00) Guam, Port Moresby

(GMT+11:00) Magadan, Solomon Islands, New Caledonia

(GMT+12:00) Fiji Islands, Kamchatka, Marshall Islands

(GMT+12:00) Auckland, Wellington

(GMT+13:00) Nuku’alofa

165

170

175

180

185

190

193

195

200

201

203

205

207

210

215

220

225

227

230

235

240

245

250

255

260

265

270

275

280

285

290

300

58 Chapter 4: XML API Reference

Filters

Results cannot be filtered or sorted.

Returned elements

None.

Sample results

action-list

Availability

Breeze 4.

Description

Returns a list of Breeze web service APIs (also referred to as actions).

Caution: Not all APIs in this list are documented, and not all documented APIs are in this list.

Parameters

None.

Filters

Results cannot be filtered or sorted.

Returned elements

actions

Sample results

<results> <status code="ok" /> <actions> <action>accesskey-exec</action> <action>accesskey-info</action> <action>action-list</action> ... [other actions listed here] ... <action>user-accounts</action> <action>user-update-pwd</action> </actions> </results>

action-list 59

common-info

Availability

Breeze 4.

Description

Provides basic information about the current user and server.

If you call the

Parameters

None.

Filters

Results cannot be filtered or sorted.

Returned elements

common

Sample results

Firefox/1.0

</common>

</results>

common-info without logging in first, the same information is returned, except that

user tag is not included, and the account-id value may be different.

<cookie>breezm5qtgnye46zpckbf.MARIANNE</cookie> <date>2004-02-12T15:53:19.797-07:00</date> <host>http://admin.breeze.example.com</host> <url>/api/xml?action=common-info</url> <version>breeze_402_r116</version> <account account-id="222914" /> <user user-id="503562">

<name>Greg Erweck</name>

<login>gerweck@example.com</login> </user> <user-agent>

Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7.5) Gecko/20041107

</user-agent>

custom-field-update

Availability

Breeze 4. This API is not supported in Breeze 5.

This API was replaced by the

Description

Updates the specified account custom field. Creates a new custom field if none exists.

60 Chapter 4: XML API Reference

acl-field-update API.

Parameters

field-id

The ID of the field to be updated (can be obtained by calling the custom-fields

API). This parameter needs to be specified only when updating an existing field.

name The name of the custom field (can be 1 to 60 characters long).

comments Any comments on the custom field (can be 0 to 60 characters long). This parameter

is optional.

type The type of the custom field. Must be one of the following:

Value Description

required

optional

optional-no-self-reg

custom-seq The custom field number. Specify this parameter only when creating a new

custom field (should be one more than the current maximum value of

Returned elements

Required account custom field

Optional and show during self-registration

Optional and hide during self-registration

custom-seq).

When updating an existing custom field: No elements are returned.

When creating a new custom field:

Sample Results:

field.

When creating a new custom field:

<results> <status code="ok" /> <field field-id="1562" account-id="7" custom-seq="4" type="optional"> <comments>none</comments> <name>Manager</name> </field> </results>

When updating an existing custom field:

custom-fields

Availability

Breeze 4. This API is not supported in Breeze 5.

This API was replaced by the

Description

Lists the custom fields of an account and the details of the fields.

acl-field-list API.

custom-fields 61

Parameters

None.

Filters

Results can be filtered only on field-id. You can also use the filter-out modifier on the type parameter.

Results cannot be sorted. The default sort is by ascending

Returned elements

custom-fields

Sample results

<name>Department</name> <comments>this is optional</comments>

</field> <field field-id="1330" custom-seq="2" account-id="7" type="required"> <name>SSN</name> </field>

</custom-fields> </results>

, field

field-id.

custom-fields-delete

Availability

Breeze 4.

Description

Deletes the specified account custom field.

Parameters

field-id The ID of the field to be deleted (call the custom-fields API to obtain the ID).

Returned elements

None.

Filters

Results cannot be filtered or sorted.

Sample results

62 Chapter 4: XML API Reference

See also

acl-field-info

, acl-field-list, acl-field-update

group-membership-update

Availability

Breeze 4.

Description

Adds one or more principals to a group, or removes one or more principals from a group.

To update multiple principals and groups, specify multiple trios of and

is-member parameters. For more information, see “About parameters” on page 16.

Parameters

group-id

principal-id The ID of the principal whose membership status you want to update.

is-member Indicates whether the principal is added to (true) or deleted from (false) the

The ID of the group for which you are updating the membership.

group.

Filters

Results cannot be filtered or sorted.

Returned elements

None.

group-id, principal-id,

Sample results

</results>

learning-path-info

Availability

Breeze 5.

Description

Returns a list of learning paths for a learning object that belongs to a curriculum. A learning object is any SCO that has been added to a curriculum. A learning path is determined by rules that establish whether a student can proceed to the next learning object or not. For example, you can create a learning path by establishing prerequisite requirements, completion requirements, or preassessment requirements.

Note: A call to the learning-path-info API describes the relationship between SCOs within a curriculum; it does not list the complete contents of a curriculum. To see the contents of a curriculum, call

sco-expanded-contents.

learning-path-info 63

Parameters

curriculum-id

sco-id The ID of the learning object.

Filters

The ID of the curriculum to which this learning object belongs.

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

current-sco-id

curriculum-id

name

path-type

permission-id

target-sco-id

The

target-sco-id field contains the ID of the learning object that restricts access to the

Filter and sort

current learning object. For example, if a learning object has a prerequisite requirement, the prerequisite SCO would be the

The

path-type field has the following possible values:

target-sco-id.

• completion-none

• completion-required

• preass-blocked

• preass-hidden

• preass-none

• prereq-hidden

• prereq-none

• preass-optional

• prereq-required

• prereq-suggested

Returned elements

learning-paths

Sample results

To understand the XML results, consider the following reading of the first learning-path tag.

The current SCO (5400246) has a completion requirement. The completion requirement is target SCO (5400247). The target SCOs name is New Hire Safety.

64 Chapter 4: XML API Reference

<learning-path curriculum-id="5400246" current-sco-id="5400246" target-

sco-id="5400247" path-type="completion-required">

<name>New Hire Safety</name> </learning-path> <learning-path curriculum-id="5400246" current-sco-id="5400246" target-

sco-id="5400248" path-type="completion-required">

<name>Beginning Electronics</name> </learning-path> <learning-path curriculum-id="5400246" current-sco-id="5400246" target-

sco-id="5400413" path-type="completion-required">

<name>Electronics 2</name> </learning-path> <learning-path curriculum-id="5400246" current-sco-id="5400246" target-

sco-id="5400414" path-type="completion-required">

<name>Electronics 3</name> </learning-path> <learning-path curriculum-id="5400246" current-sco-id="5400249" target-

sco-id="5400248" path-type="prereq-suggested">

<name>Beginning Electronics</name> </learning-path> <learning-path curriculum-id="5400246" current-sco-id="5400413" target-

sco-id="5400248" path-type="prereq-required">

<name>Beginning Electronics</name> </learning-path> <learning-path curriculum-id="5400246" current-sco-id="5400414" target-

sco-id="5400413" path-type="prereq-required">

<name>Electronics 2</name> </learning-path>

</learning-paths>

</results>

See also

learning-path-update

Availability

Breeze 5.

Description

Updates the learning path for a single learning object in a curriculum. A learning object is any SCO that is added to a curriculum.

Parameters

curriculum-id The ID of the curriculum to which this learning object belongs.

current-sco-id The ID of the learning object.

target-sco-id The ID of the learning object that restricts access to the current learning

object. For example, if a learning object has a prerequisite requirement, the prerequisite SCO would be the

target-sco-id.

learning-path-update 65

target-sco-id The ID of the learning object that restricts access to the current learning

object. For example, if a learning object has a prerequisite requirement, the prerequisite SCO is the

target-sco-id.

Consider the following scenario: a student must pass the “Intro to Programming” class before taking the “Intermediate Programming” class. In this example, “Intermediate Programming” would be represented by the

prereq-req and the target-sco-id would be “Intro to Programming.”

path-type The path-type field has the following possible values:

current-sco-id attribute, the path-type attribute would be

• completion-none

• completion-required

• preass-blocked

• preass-hidden

• preass-none

• prereq-hidden

• prereq-none

• preass-optional

• prereq-required

• prereq-suggested

Filters

The results cannot be sorted or filtered.

Returned elements

None.

Sample results

</results>

See also

learning-path-info

login

Availability

Breeze 4.

Description

Logs in a user to a Breeze server.

After logging in, you must read and store the cookie called in the HTTP headers of the XML results. You must then include the value of that cookie in every subsequent request that you make as that logged-in user.

66 Chapter 4: XML API Reference

BREEZESESSION, which can be found

The following Java example parses the HTTP headers to store the cookie, and then indicates how it can be passed on for all subsequent requests:

URL loginUrl=new URL(baseUrl + "api/xml?action=login&login=" + login +

"&password=" + password);

URLConnection conn=loginUrl.openConnection(); conn.connect();

InputStream resultStream=conn.getInputStream(); Document doc=new SAXBuilder(false).build(resultStream);

String cookieString=(String) (conn.getHeaderField("Set-Cookie"));

StringTokenizer st=new StringTokenizer(cookieString, "="); if (st.countTokens() > 1 && st.nextToken().equals("BREEZESESSION")) {

String cookieNext=st.nextToken(); int semiIndex=cookieNext.indexOf(';'); cookie=cookieNext.substring(0, semiIndex);

}

if (cookie == null){

throw new RuntimeException("Couldn't find the Breeze cookie.");

}

To pass the BREEZESESSION cookie for all subsequent requests, use the following code:

URLConnection conn=url.openConnection(); conn.setRequestProperty("Cookie", "BREEZESESSION=" + cookie); conn.connect();

The preceding example sets the password and username variables manually. In a real application, you would probably create a form that collected the password and username and passed the variables to the code.

For a ColdFusion example, see “Logging in to Breeze” on page 29.

Parameters

account-id The ID of the account with which the user is associated. This parameter is

optional. If your organization has only one account, don’t specify an

password The user’s password.

Note: If the login or password parameter is missing or incorrect, the Breeze server returns a status code of

no-data.

Filters

account-id.

Results cannot be filtered or sorted.

Returned elements

None.

Sample results

</results>

See also

logout

Availability

Breeze 4.

Description

Logs out a user, invalidating the cookie that the application received when the user logged in.

Parameters

None.

Filters

Results cannot be filtered or sorted.

Returned elements

None.

Sample results

</results>

See also

permissions-info

Availability

Breeze 4.

Description

Provides information about principals and the permissions they have for a specified SCO. You can also pass an optional principal.

To determine the ID to use as the (possibly with a filter to limit the returned data).

68 Chapter 4: XML API Reference

principal-id parameter to retrieve permission information about a specific

principal-id parameter, call the principal-list API

For more information about permissions, see “About permissions” on page 18.

For more information about filters, see Chapter 2, “Working with Filters,” on page 21.

Parameters

acl-id

The ID of a specific SCO.

principal-id The ID of a specific principal. This parameter is optional.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

description

has-children

is-primary

name

permission-id

type

Note: The logged-in-access and public-access fields are always returned in the data set, regardless of the filter restrictions.

Filter and sort

For more information about filtering and sorting, see Chapter 2, “Working with Filters,” on

page 21.

Returned elements

permissions

Sample results

The following XML data is returned when the principal-id parameter is not passed and contains information about all principals:

<principal principal-id="181248" is-primary="false" type="user"

has-children="false" permission-id="view"> <name>Englesberg, Ari</name> <login>englesberg@example.com</login>

</principal> <principal principal-id="181249" is-primary="false" type="user"

has-children="false" permission-id="view"> <name>Milligan, Susan</name> <login>milligan@example.com</login>

</principal>

</permissions>

</results>

permissions-info 69

The following XML data is returned when the principal-id parameter is passed:

</results>

If the principal was not assigned permissions to the SCO, the status code no-data is returned.

See also

permissions-reset

, permissions-update

permissions-reset

Availability

Breeze 4.

Description

Resets all principals’ permissions for the specified SCO, so the permissions of the SCO’s parent apply to all principals.

For information about permissions, see “About permissions” on page 18.

Parameters

acl-id

The ID of a SCO.

Filters

Results cannot be filtered or sorted.

Returned elements

None.

Sample results

</results>

See also

permissions-info

, permissions-update

permissions-update

Availability

Breeze 4.

Description

Updates one or more principals’ permissions for one or more SCOs.

For information about principals, see “About principals, SCOs, and IDs” on page 17.

70 Chapter 4: XML API Reference

For information about permissions, see “About permissions” on page 18.

To update multiple principals’ permissions, specify multiple trios of and

principal-id parameters. For more information, see “About parameters” on page 16.

Parameters

acl-id

The ID of a SCO.

permission-id The ID of a permission.

principal-id The ID of a principal (a user or group).

Filters

Results cannot be filtered or sorted.

Returned elements

None.

Sample results

</results>

See also

permissions-info

, permissions-reset

principal-info

acl-id, permission-id,

Availability

Breeze 4.

Description

Provides information about the specified principal. The specified principal can be a user or a group.

To determine the ID to use as the

principal-id parameter, call the principal-list API

(possibly with a filter to limit the returned data) to return an ID for the principal.

For information about principals, see “About principals, SCOs, and IDs” on page 17.

Parameters

principal-id

Filters

The ID of a specific principal.

Results cannot be filtered or sorted.

Returned elements

principal

principal-info 71

Sample results

<status code="ok" /> <principal account-id="222914" has-children="true" is-primary="true"

principal-id="222926" type="course-admins">

<description>Course managers group</description> <login>Course Managers</login> <name>Course Managers</name>

</principal>

</results>

The following sample XML data is returned when the type attribute of the principal element is

group:

<status code="ok" /> <principal account-id="7" has-children="true" is-primary="false"

principal-id="122" type="group">

</principal>

</results>

When the type attribute of the principal element is user, additional data about the user contact information, user profile, and custom fields for the user is returned, as shown in the following XML data:

<email>test4-lnagaraj@test.enang.com</email> <first-name>test4</first-name>

<last-name>laxmi</last-name> </contact> <preferences acl-id="653" lang="en" time-zone-id="4" /> <principal account-id="7" has-children="false" is-primary="false"

principal-id="653" type="user">

<login>test4-lnagaraj@test.enang.com</login>

<name>test4 laxmi</name> </principal> <principal-custom-field-values>

<field field-id="652" custom-seq="1" account-id="7" type="optional"

principal-id="653">

<name>Phone number</name>

</field> </principal-custom-field-values>

</results>

See also

principal-list

72 Chapter 4: XML API Reference

, principal-list-by-field, principal-update, principals-delete.

principal-list

Availability

Breeze 4.

Description

Provides a complete list of users and groups, including primary groups.

Parameters

None.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

contact-id

description

has-children

is-hidden

is-primary

name

principal-list

type

Filter and sort

For more information about filtering and sorting, see Chapter 2, “Working with Filters,” on

page 21.

Returned elements

principal-list

Sample results

<name>Enterprise Administrator</name> <login>lraj@macromedia.com</login>

<email>lraj@macromedia.com</email> </principal> <principal principal-id="18" contact-id="" type="authors" has-

children="true" is-primary="true" is-hidden="0">

<name>Account Authors</name>

<login>Account Authors</login>

<description>Account authors group</description>

principal-list 73

</principal>

</principal-list>

</results>

See also

principal-info

, principal-update, principal-list-by-field, principals-delete.

principal-list-by-field

Availability

Breeze 5.

Description

Allows you to list principals that have a given field value.

Parameters

value

The field value on which you want to search.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

account-id

principal-id

type

has-children

is-primary

name

description

Filter and sort

For more information about filtering and sorting, see Chapter 2, “Working with Filters,” on

page 21.

Returned elements

principal-list

Sample results

<principal account-id="7" principal-id="10018" type="user" has-

children="false" is-primary="false" is-hidden="false">

<login>jdoe@macromedia.com</login>

<description>Example User</description>

74 Chapter 4: XML API Reference

</principal>

</principal-list>

</results>

See also

principal-info

, principal-list, principal-update, principals-delete

principal-update

Availability

Breeze 4.

Description

Updates information for a principal in the current account or creates a new principal. For information about principals, see “About principals, SCOs, and IDs” on page 17.

In most cases, you must acquire the original version of the principal’s information (using

principal-info) before calling the principal-update API.

To create a new principal, call the parameter. If you create a new principal, the returned XML provides information about the new principal, including the principal’s ID.

In Breeze 4, the must call

Parameters

description

first-name The new first name to assign to the user. Use only when creating or updating a

principal-update API allowed you to update custom fields. In Breeze 5, you

acl-field-update to update fields.

The new group’s description. Use only when creating a new group.

user.

has-children Indicates whether the principal has children. If the principal is a group, set this

parameter to 1. If the principal is a user, set this parameter to 0.

principal-update API without specifying a principal-id

last-name The new last name to assign to the user. Use only when creating or updating a user.

parameter must be specified only when creating or updating a user.

name The new group’s name. Use only when creating a new group.

password The new user’s password. Use only when creating a new user.

principal-id The ID of the principal for which you are changing data. If you omit this

parameter, the

type The type of the new principal. Use only when creating a new principal. For information

principal-update API creates a new principal.

about the available types, see “About principals, SCOs, and IDs” on page 17.

Filters

Results cannot be filtered or sorted.

principal-update 75

Returned elements

If you update an existing principal, no elements are returned.

If you create a new principal, for

principal-info).

Sample results

principal is returned (in the same format as the returned elements

The following sample results are for creating a new principal:

<login>jake3@example.com</login> <name>doe, jake</name>

</principal>

</results>

See also

principal-info

, principals-delete, principal-list, principal-list-by-field

principals-delete

Description

Deletes one or more principals.

To delete multiple principals, specify multiple see “About parameters” on page 16.

Parameters

principal-id

Filters

The ID of a principal to delete.

Results cannot be filtered or sorted.

Returned elements

None.

Sample results

</results>

See also

principal-info

, principal-list, principal-list-by-field, principal-update

principal-id parameters. For more information,

76 Chapter 4: XML API Reference

report-account-meeting-attendance

Availability

Breeze 4. This API is not supported in Breeze 5.

To discover which principals attended which meetings, use the the

report-bulk-consolidated-transactions API.

Description

Returns the meeting attendance log for the account.

Parameters

None.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

date-closed

date-created

participant-name

principal-id

sco-name

tr.sco_id

transcript-id

Filter and sort

Sort

Filter and sort

Sort

Filter and sort

report-meeting-attendance or

Returned elements

report-account-meeting-attendance

Sample results

<row account-id="7" transcript-id="670" sco-id="623" principal-id="8"

contact-id="3">

<login>lraj@macromedia.com</login>

<sco-name>test-mtg-1</sco-name>

<date-closed>2004-07-09T13:02:55.810-07:00</date-closed>

<login>lraj@macromedia.com</login> <session-name>Enterprise Administrator</session-

<session-name>Enterprise Administrator</session-name>

<date-created>2004-07-09T13:00:28.920-07:00</date-created>

<participant-name>Enterprise Administrator</participant-name> </row> <row account-id="7" transcript-id="685" sco-id="623" principal-id="8"

contact-id="3">

report-account-meeting-attendance 77

name> <sco-name>test-mtg-1</sco-name> <date-created>2004-07-09T14:33:06.577-07:00</date created> <date-closed>2004-07-09T14:33:43.547-07:00</date closed> <participant-name>Enterprise Administrator</participant name>

</row>

</report-account-meeting-attendance> </results>

report-active-meeting-presenters

Availability

Breeze 4.

Description

Provides a list of the users who are currently presenting meetings.

Parameters

sco-id

The ID of a meeting; if specified, the report returns information about that meeting

only. This parameter is optional.

Filters

Results cannot be filtered or sorted.

Returned elements

report-active-meeting-presenters

Sample results

<name>Jack Monson</name>

<date-created>2004-02-17T17:06:23.920-08:00</date-created> </sco> <sco sco-id="566058">

<date-created>2004-02-17T16:50:00.327-08:00</date-created> </sco>

</report-active-meeting-presenters>

</results>

78 Chapter 4: XML API Reference

report-active-meetings

Availability

Breeze 4.

Description

Provides a list of meetings that are currently in progress.

Parameters

None.

Filters

Results cannot be filtered or sorted.

Returned elements

report-active-meetings

Sample results

<name>022305 Stephanie Test</name>

<url-path>/r27873068/</url-path>

<date-created>2005-02-28T16:09:28.510-08:00</date-created> </sco> <sco sco-id="38345152" active-participants="1" length-minutes="1">

<name>Status Meeting</name>

<url-path>/status/</url-path>

<date-created>2005-02-28T16:10:21.353-08:00</date-created> </sco>

</report-active-meetings>

</results>

report-bandwidth

Availability

Breeze 4. This API is not supported in Breeze 5.

Description

Indicates the total bandwidth consumed in the current account since the account was created, in bytes.

Parameters

None.

Filters

Results cannot be filtered or sorted.

report-bandwidth 79

Returned elements

report-bandwidth

Sample results

</results>

report-bulk-consolidated-transactions

Availability

Breeze 5

Description

Returns information about all of the transactions in an account. A transaction is an instance of one principal visiting one SCO. Consider the following examples:

• If a principal attends a meeting twice, there are two transactions for that principal: one for each

time that she attended the meeting.

• If five people attend a meeting, there are five transactions for that meeting SCO: one for each

user who attended the meeting.

• If a principal takes two courses three times and passes each only on the third try, there are six

transactions for the principal between the two courses: one for each attempt on each course.

Parameters

None.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

date-created

name

principal-id

score

status

transaction-id

url

user-name

Returned elements

report-bulk-consolidated-transactions

80 Chapter 4: XML API Reference

Filter and sort

Sample results

<name>Default Meeting Template</name>

<login>bharm@macromedia.com</login>

<user-name>Ben Harm</user-name>

<status>completed</status>

<date-created>2005-01-29T14:02:04.733-08:00</date-created> </row> <row transaction-id="4832819" principal-id="181271" score="0">

<name>Default Meeting Template</name>

<login>gho@macromedia.com</login>

<user-name>Gung Ho</user-name>

<status>completed</status>

<date-created>2005-01-04T10:10:09.077-08:00</date-created> </row>

</report-bulk-consolidated-transactions>

</results>

See also

report-bulk-objects users

, report-bulk-questions, report-bulk-slide-views, report-bulk-

report-bulk-content-quiz

Availability

Breeze 4. This API is not supported in Breeze 5.

This API was replaced by the following APIs:

report-quiz-interactions.

Description

report-bulk-questions and

Returns information about all quizzes, including a list of quizzes, and the questions and answers for each quiz. The information returned is similar to the “Content Quiz Information” download report, except that XML data is returned instead of CSV-formatted data.

Parameters

None.

Filters

Results cannot be filtered or sorted.

Returned elements

report-bulk-content-quiz

report-bulk-content-quiz 81

Sample results

- <report-bulk-content-quiz> <row presentation-id="720" quiz-id="1" quiz-passing-score="10" question-

number="1" question-value="10" answer-id="1"> <presentation-name>test-quiz</presentation-name> <quiz-name>Quiz test 1</quiz-name> <question-text>Who is Randy Johnson ?</question-text> <answer-text>A baseball pitcher with the Arizona Diamondbacks</answer-

text> <answer-correct>YES</answer-correct> </row>

- <row presentation-id="720" quiz-id="1" quiz-passing-score="10" question-

number="1" question-value="10" answer-id="2"> <presentation-name>test-quiz</presentation-name> <quiz-name>Quiz test 1</quiz-name> <question-text>Who is Randy Johnson ?</question-text> <answer-text>A basketball player with the New Jersey Nets</answer-text> <answer-correct>NO</answer-correct> </row> </report-bulk-content-quiz> </results>

report-bulk-content-quiz-results

Availability

Breeze 4. This API is not supported in Breeze 5.

This API was replaced by the following APIs:

report-quiz-question-distribution, report-quiz-question-response, report-quizsummary

Description

, report-quiz-takers.

report-quiz-interactions,

Returns results for a content quiz, including information about each user and quiz question. The returned information is similar to the “Content Quiz Responses and Results” download report, except that the

report-bulk-quiz-results API returns XML data instead of CSV-formatted

data.

Caution: There was an issue with the formatting of the time-taken XML tag, which has been fixed in the Breeze 4.1 updater. If you see incorrect formatting in the content of a download the updater from the Licensed Support Center.

Parameters

time-taken XML tag,

None.

82 Chapter 4: XML API Reference

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

date-time-attempted

presentation-attempt-id

presentation-id

question-number

quiz-id

user-id

user-login

user-response

Returned elements

report-bulk-content-quiz-results

Sample results

<report-bulk-content-quiz-results>

<row user-id="8" presentation-attempt-id="725" presentation-id="720"

quiz-id="1" question-number="1" user-response="1">

<user-login>lraj@macromedia.com</user-login> <date-time-attempted>2004-07-13T10:51:35.047-07:00</date-time-

attempted>

<time-taken>00:00:28.017</time-taken> </row> <row user-id="8" presentation-attempt-id="726" presentation-id="720"

quiz-id="1" question-number="2" user-response="3">

<user-login>lraj@macromedia.com</user-login>

<date-time-attempted>2004-07-13T10:52:23.780-07:00</date-time-

attempted>

<time-taken>00:00:45.046</time-taken> </row>

</report-bulk-content-quiz-results> </results>

Filter only

Filter and sort

Filter only

Filter and sort

Filter only

report-bulk-content-slide-views

Availability

Breeze 4. This API is not supported in Breeze 5.

This API was replaced by the

Description

Returns slide view data for content. This is similar to the “Content Slide Views” download report, except that the API returns XML data and the report returns CSV-formatted data.

report-bulk-slide-views API.

report-bulk-content-slide-views 83

Parameters

None.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

presentation-id

presentation-name

slide-number

user-first-name

user-last-name

user-login

view-date-time

Returned elements

report-bulk-slide-views

Sample results

<report-bulk-slide-views>

<row session-id="10000022" viewing-session="32" presentation-id="27"

slide-number="1">

<user-login>lraj@macromedia.com</user-login> <user-first-name>Enterprise</user-first-name>

<user-last-name>Administrator</user-last-name> <presentation-name>test-slide</presentation-name> <view-date-time>2004-06-30T11:46:10.280-07:00</view-date-time> </row>

<row session-id="10000022" viewing-session="32" presentation-id="27"

slide-number="2">

<user-login>lraj@macromedia.com</user-login>

<user-first-name>Enterprise</user-first-name>

<user-last-name>Administrator</user-last-name>

<presentation-name>test-slide</presentation-name>

<view-date-time>2004-06-30T11:46:12.500-07:00</view-date-time>

</row>

</report-bulk-slide-views>

</results>

Sort

Filter and sort

Sort

84 Chapter 4: XML API Reference

report-bulk-course-quiz

Availability

Breeze 4. This API is not supported in Breeze 5.

Description

Returns information about all course quizzes, including a list of quizzes, and the questions and answers for each quiz. The returned results are similar to the “Course Quiz Information” report, except that the API returns XML data and the report contains downloadable CSV-formatted data.

Parameters

None.

Filters

Results cannot be filtered or sorted.

Returned elements

report-bulk-course-quiz

Sample results

<report-bulk-course-quiz>

<row course-id="727" quiz-id="1" quiz-passing-score="10" question-

number="1" question-value="10" answer-id="1">

<presentation-name>quiz-course-ln</presentation-name> <quiz-name>Quiz test 1</quiz-name> <question-text>Who is Randy Johnson ?</question-text> <answer-text>A baseball pitcher with the Arizona Diamondbacks</answer-

text>

<answer-correct>YES</answer-correct> </row> <row course-id="727" quiz-id="1" quiz-passing-score="10" question-

number="1" question-value="10" answer-id="2">

<presentation-name>quiz-course-ln</presentation-name> <quiz-name>Quiz test 1</quiz-name> <question-text>Who is Randy Johnson ?</question-text> <answer-text>A basketball player with the New Jersey Nets</answer-text> <answer-correct>NO</answer-correct>

</row>

</report-bulk-course-quiz>

</results>

report-bulk-course-quiz 85

report-bulk-course-results

Availability

Breeze 4. This API is not supported in Breeze 5.

This API was replaced by the

Description

Returns results for a course quiz, including information on each user and quiz question. The returned data is similar to the “Course Quiz Responses and Results” report, except that the API returns XML data and the report returns CSV-formatted data.

Parameters

None.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

course-attempt-id

course-id

date-time-attempted

quiz-id

question-number

time-taken

user-id

user-login

user-response

report-quiz-interactions API.

Sort

Filter and sort

Sort

Filter and sort

Sort

Returned elements

report-bulk-course-quiz-results

Sample results

<report-bulk-course-quiz-results>

<row user-id="8" course-attempt-id="730" course-id="727" quiz-id="1"

question-number="1" user-response="2">

<user-login>lraj@macromedia.com</user-login> <date-time-attempted>2004-07-13T10:54:09.030-07:00</date-time-

attempted>

<time-taken>00:00:14.017</time-taken> </row> <row user-id="8" course-attempt-id="730" course-id="727" quiz-id="1"

question-number="2" user-response="1">

<user-login>lraj@macromedia.com</user-login>

86 Chapter 4: XML API Reference

<date-time-attempted>2004-07-13T10:54:09.030-07:00</date-time-

attempted> <time-taken>00:00:34.017</time-taken> </row> </report-bulk-course-quiz-results> </results>

Caution: There was an issue with the formatting of the the Breeze 4.1 updater. If you see incorrect formatting in the content of a download the updater from the Licensed Support Center.

time-taken XML tag, which has been fixed in

time-taken XML tag,

report-bulk-meeting

Availability

Breeze 4. This API is not supported in Breeze 5.

This API was replaced by the following example:

http://breezeserver/api/xml?action=report-bulk-objects&filter-like-

type=meeting

Description

Returns information about all meetings. Similar to the Meeting Information report, except that the API returns XML data and the report returns CSV-formatted data.

Parameters

None.

report-bulk-objects API and filter on the type field, as in the

Filters

Results cannot be filtered or sorted.

Returned elements

report-bulk-meeting

Sample results

<report-bulk-meeting>

<meeting-name>test-mtg-1</meeting-name> <meeting-scheduled-date-time>2004-07-07T10:00:00.000-07:00</meeting-

scheduled-date-time>

</row> <row meeting-id="679" invited-participants="2">

<meeting-name>test-mtg-2</meeting-name> <meeting-scheduled-date-time>2004-07-09T14:00:00.000-07:00</meeting-

scheduled-date-time>

</row> </report-bulk-meeting> </results>

report-bulk-meeting 87

report-bulk-meeting-attendance

Availability

Breeze 4. This API is not supported in Breeze 5.

Description

Returns meeting attendance data. The results are similar to the “Meeting Attendance” report, except that the API returns XML data and the report returns downloadable CSV-formatted data.

Parameters

None.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

attendee

attendee-exit

attendee-join

meeting-attendee

meeting-id

meeting-name

Sort

Returned elements

report-bulk-meeting-attendance

Sample results

<report-bulk-meeting-attendance>

<meeting-name>test-mtg-1</meeting-name> <attendee>Enterprise Administrator</attendee> <attendee-join>2004-07-09T13:00:28.920-07:00</attendee-join>

<attendee-exit>2004-07-09T13:02:55.810-07:00</attendee-exit> </row> <row meeting-id="623" meeting-attendee="8">

<meeting-name>test-mtg-1</meeting-name>

<attendee>Enterprise Administrator</attendee>

<attendee-join>2004-07-09T14:33:06.577-07:00</attendee-join>

<attendee-exit>2004-07-09T14:33:43.547-07:00</attendee-exit> </row>

</report-bulk-meeting-attendance> </results>

88 Chapter 4: XML API Reference

report-bulk-objects

Availability

Breeze 5.

Description

Returns information about every object on the Breeze server. Object types include archive, attachment, authorware, captivate, course, curriculum, external-event, FLV, image, meeting, presentation, and SWF.

Use filters to limit the returned XML. For example, to return a list of all the meetings in an account, filter on the

http://breezeserver/api/xml?action=report-bulk-objects&filter-like-

type=meeting

Parameters

None.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

date-modified

name

type

url

type field, as in the following example:

Filer and sort

Filter and sort

Caution: In Breeze 5, you can’t filter the type field for a specific value; you must use the like modifier. For example, in the following code, the first line throws an exception, but the second line executes correctly:

http://breezeserver/api/xml?action=report-bulk-objects&filter-type=meeting http://breezeserver/api/xml?action=report-bulk-objects&filter-like-

type=meeting

Returned elements

report-bulk-objects

Sample results

<row>

<type>presentation</type>

<date-created>2003-07-14T14:54:16.757-07:00</date-created>

<date-end>2003-07-14T14:54:16.757-07:00</date-end>

<date-modified>2003-10-30T12:14:52.740-08:00</date-modified>

report-bulk-objects 89

</row> <row>

<type>presentation</type>

<name>181438 Bullet Animation Test.ppt</name>

<date-created>2003-07-14T14:54:16.757-07:00</date-created>

<date-end>2003-07-14T14:54:16.757-07:00</date-end>

<date-modified>2003-07-14T14:52:32.327-07:00</date-modified> </row>

</report-bulk-objects>

</results>

See also

report-bulk-consolidated-transactions

, report-bulk-users

views

, report-bulk-questions, report-bulk-slide-

report-bulk-questions

Availability

Breeze 5.

Description

Returns information about every quiz question in a particular account.

Parameters

None.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

date-created

principal-id

question

response

score

transaction-id

Returned elements

report-bulk-questions

Sample results

<question>Is a capacitor active?</question>

90 Chapter 4: XML API Reference

Filter and sort

<response>false</response>

<date-created>2005-03-24T16:36:36.100-08:00</date-created> </row> <row transaction-id="5335430" score="10" principal-id="4975764">

<question>Apples can be <1> or <2>. The name of the grocery store is

<3></question>

<response>{green,red,Bob's}</response>

<date-created>2005-03-24T15:16:39.030-08:00</date-created> </row> <row transaction-id="5335151" score="0" principal-id="4954032">

<question>Apples can be <1> or <2>. The name of the grocery store is

<3></question>

<date-created>2005-03-24T11:52:14.280-08:00</date-created> </row> <row transaction-id="5335144" score="10" principal-id="4954032">

<question>Apples can be <1> or <2>. The name of the grocery store is

<3></question>

<response>{red,green,Bob's}</response>

<date-created>2005-03-24T11:46:53.950-08:00</date-created> </row>

</report-bulk-questions>

</results>

See also

report-bulk-objects

, report-bulk-users

views

, report-bulk-consolidated-transactions, report-bulk-slide-

report-bulk-slide-views

Availability

Breeze 5.

Description

Returns information about every instance of a principal viewing a slide in an account.

Parameters

None.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

date-created

page

principal-id

transaction-id

Filter and sort

report-bulk-slide-views 91

Returned elements

report-bulk-slide-views

Sample results

<date-created>2005-03-24T16:36:41.820-08:00</date-created> </row> <row transaction-id="38484112" principal-id="38181502">

<date-created>2005-03-24T16:37:53.070-08:00</date-created> </row> <row transaction-id="38484112" principal-id="38181502">

<date-created>2005-03-24T16:38:09.070-08:00</date-created> </row> <row transaction-id="38484112" principal-id="38181502">

<date-created>2005-03-24T16:36:47.663-08:00</date-created> </row> <row transaction-id="38484112" principal-id="38181502">

<date-created>2005-03-24T16:37:04.303-08:00</date-created> </row> <row transaction-id="38484112" principal-id="38181502">

<date-created>2005-03-24T16:37:15.710-08:00</date-created> </row> <row transaction-id="38484112" principal-id="38181502">

<date-created>2005-03-24T16:38:29.833-08:00</date-created> </row>

</report-bulk-slide-views>

</results>

See also

report-bulk-objects transactions

92 Chapter 4: XML API Reference

, report-bulk-users

, report-bulk-questions, report-bulk-consolidated-

report-bulk-users

Availability

Breeze 5.

Description

Returns information about all users in an account. Remember to use filters to limit your results. For example, the following call returns in ascending order all users who have the letters “Jo” in their name:

http://admin.ibreeze.macromedia.com/api/xml?action=report-bulk-users&sort-

name=asc&filter-like-name=Jo

Parameters

None.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

manager

name

principal-id

type

Filter and sort

Caution: In Breeze 5, you can’t filter the type field for a specific value; you must use the like modifier. For example, in the following code the first line throws an exception, but the second line executes correctly:

http://breezeserver/api/xml?action=report-bulk-objects&filter-

type=presentation

http://breezeserver/api/xml?action=report-bulk-objects&filter-like-

type=presentation

Returned elements

report-bulk-users

Sample results

<login>nson@macromedia.com</login>

<name>Nathan Son</name>

<email>nson@macromedia.com</email>

<manager>cberet@macromedia.com</manager>

report-bulk-users 93

<login>vish_laxmi@yahoo.com</login>

<name>laxmi vish</name>

<email>vish_laxmi@yahoo.com</email>

<login>acobbler@macromedia.com</login>

<name>Apple Cobbler</name>

<email>acobbler@macromedia.com</email>

<manager>pangel@macromedia.com</manager>

</report-bulk-users>

</results>

See also

report-bulk-objects consolidated-transactions

, report-bulk-questions, report-bulk-slide-views, report-bulk-

report-course-status

Availability

Breeze 4.

Description

Returns course status for either a principal or a SCO, based on the parameters passed in.

Parameters

principal-id

sco-id The ID of the SCO for which the course status is requested.

Note: Only one of the principal-id or sco-id parameters needs to be passed in, based on the type of information needed.

Filters

The ID of the principal for whom the course status is requested.

Results cannot be filtered or sorted.

Returned elements

report-course-status

Sample results

When the sco-id parameter is passed in, the following XML may be returned:

<date-last-taken>2004-07-13T10:55:28.763-07:00</date-last-taken>

94 Chapter 4: XML API Reference

</report-course-status> </results>

When the principal-id parameter is passed in, the following XML may be returned:

<report-course-status total-course-completions="4" total-unique-course-

completions="4" num-passed="3" num-failed="1">

<date-last-taken>2004-07-27T12:53:42.297-07:00</date-last-taken>

</report-course-status> </results>

report-course-takers

Availability

Breeze 4. This API is not supported in Breeze 5.

This API was replaced by

Description

report-quiz-takers.

Provides a list of the users enrolled in the specified course.

Parameters

sco-id

The ID of a course.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

answered-survey

date-taken

certificate

percentage-score

principal-name

sco-id

status

transcript-id

time-taken

The data can be sorted on any of the custom fields that exist for the account. You cannot filter on any custom field.

Sort

Filter and sort

Sort

Filter and sort

Sort

Filter and sort

Sort

For more information about filtering and sorting, see Chapter 2, “Working with Filters,” on

page 21.

report-course-takers 95

Returned elements

report-quiz-takers

Sample results

<row transcript-id="13106" sco-id="13105" principal-id="10021"

status="user-passed" score="2" certificate="13106" attempts="1">

<login>bcassaly@macromedia.com</login>

<date-taken>2005-03-02T16:00:33.170-08:00</date-taken>

<principal-name>Bart Cassaly</principal-name> </row> <row transcript-id="13110" sco-id="13105" principal-id="11211"

status="user-failed" score="0" certificate="13110" attempts="1">

<login>gbest@macromedia.com</login>

<date-taken>2005-03-02T16:03:36.750-08:00</date-taken>

<principal-name>George Best</principal-name> </row> <row transcript-id="14102" sco-id="13105" principal-id="12029"

status="user-passed" score="2" certificate="14102" attempts="4">

<login>bart1cassaly@yahoo.com</login>

<date-taken>2005-03-04T16:37:31.077-08:00</date-taken>

<principal-name>Finbarr Cassidy</principal-name> </row>

</report-quiz-takers>

</results>

report-disk-usage

Availability

Breeze 4. This API is not supported in Breeze 5.

Description

Provides information about how much hard disk space the Breeze content for the current account uses, in bytes. Includes all content and archives.

Parameters

None.

Filters

Results cannot be filtered or sorted.

Returned elements

report-disk-usage

Sample results

</results>

96 Chapter 4: XML API Reference

report-meeting-attendance

Availability

Breeze 4.

Description

Provides a list of users who have attended the specified meeting. If the meeting hasn’t started, the returned data contains no rows.

The data does not include users who were invited but did not attend the meeting.

Parameters

sco-id

The ID of a meeting.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

answered-survey

date-created

date-end

participant-name

principal-id

sco-id

sco-name

session-name

transcript-id

Filter and sort

For more information about filtering and sorting, see Chapter 2, “Working with Filters,” on

page 21.

Returned elements

report-meeting-attendance

Sample results

<row transcript-id="18308" sco-id="18302" principal-id="10021" answered-

survey="0">

<login>bcassaly@macromedia.com</login>

<session-name>Bart Cassaly</session-name>

<sco-name>8th Meeting</sco-name>

<date-created>2005-03-15T10:11:00.700-08:00</date-created>

report-meeting-attendance 97

<date-end>2005-03-15T10:13:12.810-08:00</date-end>

<participant-name>Bart Cassaly</participant-name> </row>

</report-meeting-attendance>

</results>

report-meeting-concurrent-users

Availability

Breeze 4.

Description

Indicates the maximum number of users who can participate simultaneously in the specified meeting. This maximum is determined by the account license.

Parameters

sco-id

The ID of a meeting.

Filters

Results cannot be filtered or sorted.

Returned elements

report-meeting-concurrent-users

Sample results

<status code="ok" /> <report-meeting-concurrent-users max-users="426"

max-participants-freq="1" />

</results>

report-meeting-session

Availability

Breeze 4. This API is not supported in Breeze 5.

In Breeze 5 you can call the return data for a specific meeting session.

Description

Provides information about a specific meeting session, such as the session name, session starting and ending times, and the number of participants and guests who attended the session.

Each time someone enters an otherwise empty meeting, a new session starts. The session ends when all attendees leave the meeting. If someone later enters the now-empty meeting, a new session starts.

98 Chapter 4: XML API Reference

report-meeting-sessions API and filter on the asset-id field to

Parameters

sco-id

The ID of a meeting. This value must match the sco-id for a specific meeting session.

To obtain the list of all sessions and their associated

sessions

Filters

API.

Results cannot be filtered or sorted.

Returned elements

report-meeting-session

Sample results

</report-meeting-session>

</results>

See also

report-meeting-sessions

sco-ids, call the report-meeting-

Availability

Breeze 4.

Description

Provides information about all the sessions of a meeting. Each time someone enters an otherwise empty meeting, a new session starts. The session ends when all attendees leave the meeting. If someone later enters the now-empty meeting, a new session starts.

Parameters

sco-id The ID of a meeting.

Filters

The following table lists the fields on which the data can be filtered and sorted:

Field Filter/Sort

asset-id

date-created

date-end

Filter and sort

report-meeting-sessions 99

Field Filter/Sort

num-participants

sco-id

Sort

Filter and sort

For more information about filtering and sorting, see Chapter 2, “Working with Filters,” on

page 21.

Returned elements

report-meeting-sessions

Sample results

<date-created>2005-03-15T09:30:28.233-08:00</date-created>

<date-end>2005-03-15T09:45:36.903-08:00</date-end> </row> <row sco-id="18302" asset-id="18309" num-participants="1">

<date-created>2005-03-15T10:11:00.700-08:00</date-created>

<date-end>2005-03-15T10:21:07.733-08:00</date-end> </row>

</report-meeting-sessions>

</results>

report-meeting-session-slots

Availability

Breeze 4. This API is not supported in Breeze 5.

Description

Provides information about the number of attendees in every ten-minute time slot of the specified meeting session.

Parameters

sco-id

The ID of a valid meeting session. You can obtain this ID by calling the report-

meeting-session-slots

Filters

API.

Results cannot be sorted or filtered. The default sort is by the time slot starting time.

Returned elements

report-meeting-session-slots

Sample results

100 Chapter 4: XML API Reference

Macromedia BREEZE 5 INTEGRATION GUIDE

Specifications and Main Features

Frequently Asked Questions

User Manual

CONTENTS

Before You Begin

Audience

What’s new in the Breeze XML APIs

What’s changed in the Breeze XML APIs

Guide to instructional media

Additional resources

Typographical conventions

Using the Breeze XML APIs

Data flow

Calling an API on the server

Logging in to Breeze first

About parameters

About principals, SCOs, and IDs

About security

About permissions

About security and launching content

Working with Filters

About filters

Filter examples

About date formatting

About sort filters

Special filter scenarios

Filtering data that has a type field

Filtering data based on the date of a record

Filtering a specific number of entries starting at a specific entry

Filtering by membership in standard groups

Filter reference

Testing code in the browser

Where to go from here

Common Tasks

Calling your first API

Logging in to Breeze

Reviewing the code

Creating a new user

Adding a user to a group

Displaying a user’s meetings, courses, and events

Creating a meeting

Creating a meeting from a template

Creating and managing learning paths

Integrating Breeze with a directory service

Integrating Breeze with a portal

Generating reports

XML API Reference

Sample API entry

Entry title

API listing by function

Content and meeting management

Curriculum and learning path management

Custom fields

General

Permissions

Reports

User management

Alphabetical API listing

API reference entries

accesskey-exec

accesskey-info

acl-field-info

acl-field-list

acl-field-update

acl-preference-update

action-list

common-info

custom-field-update

custom-fields

custom-fields-delete

group-membership-update

learning-path-info

learning-path-update

login

logout

permissions-info

permissions-reset

permissions-update

principal-info