Macromedia BREEZE 5 INTEGRATION GUIDE

Breeze Integration Guide

Trademarks

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

Third-Party Information

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

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

Acknowledgments

Director: Erick Vera

Project Management: Stephanie Gowin

Writing: Jody Bleyle

Managing Editor: Rosana Francescato

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

Production and Editing Management: Patrice O’Neill

Media Design and Production: Adam Barnett, John Francis

First Edition: May 2005

Macromedia, Inc. 601 Townsend St.

San Francisco, CA 94103

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4 Contents

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Contents 5

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

6 Contents

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Contents 7

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

8 Contents

INTRODUCTION

Before You Begin

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

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

Audience

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

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

What’s new in the Breeze XML APIs

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

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

info

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

transactions

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

views

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

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

Updated Principals APIs include information about custom fields.

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

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

filters to locate particular SCOs.

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

, learning-path-update.

info

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

What’s changed in the Breeze XML APIs

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

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

• accesskey-exec

• accesskey-info

• report-account-meeting-attendance

• report-bandwidth

• report-bulk-content-quiz

• report-bulk-content-quiz-results

• report-bulk-content-slide-views

• report-bulk-course-quiz

• report-bulk-course-results

• report-bulk-meeting

• report-bulk-meeting-attendance

• report-course-takers

• report-disk-usage

• report-meeting-session

• report-meeting-session-slots

• report-principal-list

• report-quiz-answer-distribution

• report-quiz-definition-answers

• report-quiz-definition-questions

• report-quiz-question-totals

Guide to instructional media

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

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

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

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

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

10 Introduction: Before You Begin

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

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

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

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

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

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

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

Additional resources

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

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

provides sample code and articles about Breeze integration.

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

webservices/) is a good introduction to web services.

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

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

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

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

call web services using CFML.

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

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

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

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

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

Additional resources 11

Typographical conventions

The following typographical conventions are used in this manual:

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

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

and names of attributes.

• Boldface font indicates a verbatim entry.

12 Introduction: Before You Begin

CHAPTER 1

Using the Breeze XML APIs

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

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

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

Data flow

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

Web browser

Step 1: Web browser requests page.

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

Step 3: Application server executes code.

Step 4: Application server calls API on Breeze server.

Request

<HTML>

<code>

</HTML>

Action

WEB SERVER

Application server

Response

XML data

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

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

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

Breeze Server

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

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

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

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

14 Chapter 1: Using the Breeze XML APIs

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

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

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

POST request.

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

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

Calling an API on the server

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

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

action parameter to the web services servlet URL with a

action, which specifies

query string, as follows:

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

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

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

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

HTTP

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

x-www-form-urlencoded

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

explicitly set the content type.)

The URL to use for the query string has the form

xml?action=action_name

, with the parameters of the API appended as additional query

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

parameters separated by ampersands (&).

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

and then send an HTTP

or application/xml.

xml

The following code calls the

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

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

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

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

</params>

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

page 27.

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

Calling an API on the server 15

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

on page 18.

POST method when possible.

Logging in to Breeze first

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

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

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

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

BREEZESESSION. When you receive the

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

on page 29.

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

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

About parameters

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

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

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

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

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

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

the Breeze server.

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

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

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

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

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

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

16 Chapter 1: Using the Breeze XML APIs

</cfhttp>

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

membership-update

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

About principals, SCOs, and IDs

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

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

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

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

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

SCO Description

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

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

curriculum A Breeze curriculum.

event A Breeze event.

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

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

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

meeting A Breeze meeting.

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

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

group of users).

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

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

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

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

the user’s ID as the

principal-id parameter.

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

About principals, SCOs, and IDs 17

acl-id,

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

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

name that ends in

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

a SCO.

About security

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

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

About permissions

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

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

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

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

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

status tag.

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

18 Chapter 1: Using the Breeze XML APIs

You can specify the following permissions on a SCO:

Permission Description

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

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

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

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

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

permission on meetings or courses.

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

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

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

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

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

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

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

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

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

About security and launching content

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

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

equal to the value of the

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

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

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

BREEZESESSION login cookie, as the following example shows:

About security 19

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

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

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

BREEZESESSION, which results

in potential conflicts between Breeze and the application server.

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

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

20 Chapter 1: Using the Breeze XML APIs

CHAPTER 2

Working with Filters

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

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

About filters

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

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

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

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

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

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

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

Type-Modifier-FieldName=Value

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

on page 23.

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

Java). The following is the filter format:

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

Filter examples

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

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

a filter on the course name, for example

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

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

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

your Java courses and displays the course you started first.

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

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

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

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

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

Filter Description

filter-name=Goals Review

filter-like-name=Goals

filter-out-name=Status

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

status=active

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

name=asc

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

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

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

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

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

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

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

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

About date formatting

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

28T16:23:00.000

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

the best result. Using a value of

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

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

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

22 Chapter 2: Working with Filters

About sort filters

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

sort-name=asc

name field in ascending order:

The following code sorts the name field in descending order:

sort-name=desc

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

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

list

sort on the

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

name in each group).

You can do this by specifying the following parameters:

sort1-type=asc&sort2-name=desc

Special filter scenarios

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

page 41.

Filtering data that has a type field

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

filter-type=folder&filter-type=meeting

The following example shows all types except folder and meeting:

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

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

filter-type=null

The following example shows only types that are not null:

filter-out-type=null

folder and meeting:

null:

Filtering data based on the date of a record

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

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

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

Special filter scenarios 23

Filtering a specific number of entries starting at a specific entry

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

filter-rows=25&filter-start=100

Filtering by membership in standard groups

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

action=principal-list&filter-type=admins

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

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

Filter reference

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

Type-Modifier-FieldName=Value

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

Type Modifier Description

filter (none)

filter like

filter out

filter rows

filter start

filter gt

filter lt

filter gte

filter lte

sort (none)

Field must match value exactly.

Field must contain value.

Field cannot contain value.

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

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

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

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

Sorts results. Value must be asc or desc.

24 Chapter 2: Working with Filters

Testing code in the browser

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

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

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

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

then enter the following URL, substituting your server name for

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

name=filter&filter-like-description=date

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

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

<my-courses>

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

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

</course>

</my-courses>

</results>

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

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

<my-meetings />

</results>

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

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

breezedev.mycompany.com:

Testing code in the browser 25

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

Where to go from here

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

26 Chapter 2: Working with Filters

CHAPTER 3

Common Tasks

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

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

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

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

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

tasks are covered in this chapter:

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

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

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

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

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

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

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

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

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

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

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

Calling your first API

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

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

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

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

can call.

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

• The domain of your breeze account.

For example,

breeze.yourcompany.com.

• The name of the API you want to call.

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

To call a Breeze API in a browser:

Open a browser.

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

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

Press Enter (Windows) or Return (Macintosh).

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

API returns the following XML:

list

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

</actions>

</results>

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

on page 25.

action-

28 Chapter 3: Common Tasks

Logging in to Breeze

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

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

When you call the includes a

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

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

calls.

To log in a user to Breeze:

Create a ColdFusion page with the following content:

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

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

</cfif>

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

</form> </cfif>

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

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

Logging in to Breeze 29

Reviewing the code

The following table describes the highlighted code and its function:

Code Description

<cfset baseurl = "http://

breezeserveraddress">

<cfhttp url="#baseurl#/api/

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

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

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

<cfif

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

<cfhttp url="#baseurl#/api/

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

<cfset meetings = CFHTTP.FileContent/

<cfset meetings_xml =

XMLParse(meetings)/>

</cfif>

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

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

<input type="submit"

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

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

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

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

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

response variable. The second line converts the

string data in the document object and stores it in the

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

BREEZESESSION cookie and store it in the loginCookie variable.

Checks whether the status code attribute in the XML response is

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

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

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

response variable into an XML

xml variable.

loginHeader variable. The second line

ok.

loginCookie variable as the session

meetings variable, and

meetings variable into an XML

ok, print Login Failed.

30 Chapter 3: Common Tasks

+ 202 hidden pages

Macromedia BREEZE 5 INTEGRATION GUIDE

Specifications and Main Features

Frequently Asked Questions

User Manual

CONTENTS

Before You Begin

Audience

What’s new in the Breeze XML APIs

What’s changed in the Breeze XML APIs

Guide to instructional media

Additional resources

Typographical conventions

Using the Breeze XML APIs

Data flow

Calling an API on the server

Logging in to Breeze first

About parameters

About principals, SCOs, and IDs

About security

About permissions

About security and launching content

Working with Filters

About filters

Filter examples

About date formatting

About sort filters

Special filter scenarios

Filtering data that has a type field

Filtering data based on the date of a record

Filtering a specific number of entries starting at a specific entry

Filtering by membership in standard groups

Filter reference

Testing code in the browser

Where to go from here

Common Tasks

Calling your first API

Logging in to Breeze

Reviewing the code