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.

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>

</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 don’t 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:

<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

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

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

<cfhttp url="#baseurl#api/xml?action=principals-delete&principal-

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

About principals, SCOs, and IDs 17

</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 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:

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

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 user’s ID

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.

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

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 group’s 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 is loading ...

MACROMEDIA BREEZE 5 Integration Guide

MACROMEDIA BREEZE 5 Integration Guide

Related papers

Other documents