MACROMEDIA BREEZE 5 Integration Guide

Category
Software
Type
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
3
CONTENTS
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
4 Contents
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
Contents 5
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
6 Contents
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
Contents 7
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
8 Contents
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
9
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-
info
, acl-field-list, acl-field-update.
New Report APIs let you gather data from the Breeze server: report-bulk-consolidated-
transactions
, report-bulk-objects, report-bulk-questions, report-bulk-slide-
views
, report-bulk-users, report-bandwidth, and report-my-events.
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-
info
, learning-path-update.
10 Introduction: Before You Begin
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.
Additional resources 11
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.
12 Introduction: Before You Begin
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.
13
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.
14 Chapter 1: Using the Breeze XML APIs
Data flow
The following diagram shows an example of the flow of data in a web application that interacts
with the 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:
1.
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.
2.
The web server finds the relevant page and passes it to the application server.
3.
The application server parses and executes the ColdFusion code contained in the page.
Step 2: Web server
finds page and
passes it to
application server.
Step 4: Application
server calls API on
Breeze server.
Step 5: Breeze server
returns XML data to
application server.
Step 6: Application
server inserts data in
page and then passes
the page to the web
server.
Step 1: Web browser
requests page.
Step 3: Application
server executes code.
Step 7: Web server
sends finished page
to requesting browser.
Application server
Request
Web browser
<HTML>
<code>
</HTML>
Response
Action
<HTML>
<p>Hi</p>
</HTML>
WEB SERVER
Breeze Server
XML data
Calling an API on the server 15
4.
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
POST request.
5.
The Breeze server executes the API, returning the resulting XML data to the application server.
6.
The application server code parses the returned XML, inserts data into the web page as
appropriate, and then passes the finished page to the web server.
7.
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
action, which specifies
the name of the API. You append the
action parameter to the web services servlet URL with a
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 dont need to
explicitly set the content type.)
The URL to use for the query string has the form
http://breeze.example.com/api/
xml?action=action_name
, with the parameters of the API appended as additional query
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
POST request to the server, with the HTTP content type set to text/
xml
or application/xml.
The following code calls the
login API using a GET HTTP request:
http://admin.breezecentral.com/api/
xml?action=login&[email protected]&password=foobar
The following is the equivalent call using POST instead of GET:
<params>
<param name="action">login</param>
<param name="login">[email protected]</param>
<param name="password">foobar</param>
</params>
For example code demonstrating how to call an API, see Chapter 3, “Common Tasks,” on
page 27.
16 Chapter 1: Using the Breeze XML APIs
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
POST method when possible.
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.
Logging in to Breeze first
To call most APIs, you must be acting as a particular logged-in user, so you must call the
login
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
BREEZESESSION. When you receive the
results of a
login call, save the value of that cookie. You must include the value of the
BREEZESESSION cookie in every subsequent request that you make as that logged-in user; if you
dont 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
principal-id parameters. (This example relies on variables called baseurl
and
loginCookie, which you would set during the login process. For more information, see
“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">
About principals, SCOs, and IDs 17
<cfhttpparam type="Cookie" name="BREEZESESSION" value="#loginCookie#">
</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
group of users).
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 cant 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:
Each principal and SCO has a unique ID number. When you call an API that uses an entitys 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
acl-id,
folder-id, group-id, parent-acl-id, principal-id, sco-id, and user-id.
For example, to update a user’s password, call the
user-update-pwd API, and give the users ID
as the
user-id parameter. To determine a user’s name, call the principal-info API, and give
the users ID as the
principal-id parameter.
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.
18 Chapter 1: Using the Breeze XML APIs
There are a few other kinds of IDs that arent 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
status tag.
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.
If a particular principal has no explicitly specified permissions on a particular SCO, that
principal’s permissions on the parent of the SCO apply.
About security 19
You can specify the following permissions on a SCO:
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
group-membership-update API to add a member to a group. Use the
permissions-update API to set a groups permissions for a particular SCO.
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
BREEZESESSION login cookie, as the following example shows:
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.
Permission Description
Denied The principal cannot view, access, or manage the SCO. You cannot specify this
permission on meetings or courses.
Host (For meetings only) The host of a meeting. This permission lets the principal
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.
Manage The principal can view, delete, move, and edit the SCO. This permission also lets
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.
Publish The principal can publish the SCO to the server and can update the SCO. This
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.
View The principal can view the SCO but not modify it. For a course, the View
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.
20 Chapter 1: Using the Breeze XML APIs
You can set 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.
  • Page 1 1
  • Page 2 2
  • Page 3 3
  • Page 4 4
  • Page 5 5
  • Page 6 6
  • Page 7 7
  • Page 8 8
  • Page 9 9
  • Page 10 10
  • Page 11 11
  • Page 12 12
  • Page 13 13
  • Page 14 14
  • Page 15 15
  • Page 16 16
  • Page 17 17
  • Page 18 18
  • Page 19 19
  • Page 20 20
  • Page 21 21
  • Page 22 22
  • Page 23 23
  • Page 24 24
  • Page 25 25
  • Page 26 26
  • Page 27 27
  • Page 28 28
  • Page 29 29
  • Page 30 30
  • Page 31 31
  • Page 32 32
  • Page 33 33
  • Page 34 34
  • Page 35 35
  • Page 36 36
  • Page 37 37
  • Page 38 38
  • Page 39 39
  • Page 40 40
  • Page 41 41
  • Page 42 42
  • Page 43 43
  • Page 44 44
  • Page 45 45
  • Page 46 46
  • Page 47 47
  • Page 48 48
  • Page 49 49
  • Page 50 50
  • Page 51 51
  • Page 52 52
  • Page 53 53
  • Page 54 54
  • Page 55 55
  • Page 56 56
  • Page 57 57
  • Page 58 58
  • Page 59 59
  • Page 60 60
  • Page 61 61
  • Page 62 62
  • Page 63 63
  • Page 64 64
  • Page 65 65
  • Page 66 66
  • Page 67 67
  • Page 68 68
  • Page 69 69
  • Page 70 70
  • Page 71 71
  • Page 72 72
  • Page 73 73
  • Page 74 74
  • Page 75 75
  • Page 76 76
  • Page 77 77
  • Page 78 78
  • Page 79 79
  • Page 80 80
  • Page 81 81
  • Page 82 82
  • Page 83 83
  • Page 84 84
  • Page 85 85
  • Page 86 86
  • Page 87 87
  • Page 88 88
  • Page 89 89
  • Page 90 90
  • Page 91 91
  • Page 92 92
  • Page 93 93
  • Page 94 94
  • Page 95 95
  • Page 96 96
  • Page 97 97
  • Page 98 98
  • Page 99 99
  • Page 100 100
  • Page 101 101
  • Page 102 102
  • Page 103 103
  • Page 104 104
  • Page 105 105
  • Page 106 106
  • Page 107 107
  • Page 108 108
  • Page 109 109
  • Page 110 110
  • Page 111 111
  • Page 112 112
  • Page 113 113
  • Page 114 114
  • Page 115 115
  • Page 116 116
  • Page 117 117
  • Page 118 118
  • Page 119 119
  • Page 120 120
  • Page 121 121
  • Page 122 122
  • Page 123 123
  • Page 124 124
  • Page 125 125
  • Page 126 126
  • Page 127 127
  • Page 128 128
  • Page 129 129
  • Page 130 130
  • Page 131 131
  • Page 132 132
  • Page 133 133
  • Page 134 134
  • Page 135 135
  • Page 136 136
  • Page 137 137
  • Page 138 138
  • Page 139 139
  • Page 140 140
  • Page 141 141
  • Page 142 142
  • Page 143 143
  • Page 144 144
  • Page 145 145
  • Page 146 146
  • Page 147 147
  • Page 148 148
  • Page 149 149
  • Page 150 150
  • Page 151 151
  • Page 152 152
  • Page 153 153
  • Page 154 154
  • Page 155 155
  • Page 156 156
  • Page 157 157
  • Page 158 158
  • Page 159 159
  • Page 160 160
  • Page 161 161
  • Page 162 162
  • Page 163 163
  • Page 164 164
  • Page 165 165
  • Page 166 166
  • Page 167 167
  • Page 168 168
  • Page 169 169
  • Page 170 170
  • Page 171 171
  • Page 172 172
  • Page 173 173
  • Page 174 174
  • Page 175 175
  • Page 176 176
  • Page 177 177
  • Page 178 178
  • Page 179 179
  • Page 180 180
  • Page 181 181
  • Page 182 182
  • Page 183 183
  • Page 184 184
  • Page 185 185
  • Page 186 186
  • Page 187 187
  • Page 188 188
  • Page 189 189
  • Page 190 190
  • Page 191 191
  • Page 192 192
  • Page 193 193
  • Page 194 194
  • Page 195 195
  • Page 196 196
  • Page 197 197
  • Page 198 198
  • Page 199 199
  • Page 200 200
  • Page 201 201
  • Page 202 202
  • Page 203 203
  • Page 204 204
  • Page 205 205
  • Page 206 206
  • Page 207 207
  • Page 208 208
  • Page 209 209
  • Page 210 210
  • Page 211 211
  • Page 212 212
  • Page 213 213
  • Page 214 214
  • Page 215 215
  • Page 216 216
  • Page 217 217
  • Page 218 218
  • Page 219 219
  • Page 220 220
  • Page 221 221
  • Page 222 222
  • Page 223 223
  • Page 224 224
  • Page 225 225
  • Page 226 226
  • Page 227 227
  • Page 228 228
  • Page 229 229
  • Page 230 230
  • Page 231 231
  • Page 232 232

MACROMEDIA BREEZE 5 Integration Guide

Category
Software
Type
Integration Guide

Ask a question and I''ll find the answer in the document

Finding information in a document is now easier with AI