1

1

2OASIS Service Provisioning Markup 3Language (SPML) Version 2

4Draft Committee Specification 0.10 52005 June 7

6Document identifier: draft-pstc-SPMLv2.doc 7Location: http://www.oasis-open.org/committees/provision/docs/ 8Send comments to: [email protected] 9Editor: 10 Gary Cole, Sun Microsystems ([email protected]) 11Contributors: 12 Jeff Bohren, BMC 13 Gerry Woods, SOA Software 14 Doron Cohen, BMC 15 Darran Rolls, Sun Microsystems 16 Gavenraj Sodhi, CA 17 Hal Lockhart, BEA 18 Jeff Larson, Sun Microsystems 19 Rami Elron, BMC 20 Gary Cole, Sun Microsystems 21 Ron Jacobsen, CA 22 Martin Raepple, SAP 23 Cory Williams, IBM 24 Ian Glazer, IBM 25Abstract:

26 This specification defines the concepts and operations of an XML-based provisioning 27 request-and-response protocol. 28Status:

29 This is a candidate Committee Specification that is undergoing a vote of the OASIS 30 membership in pursuit of OASIS Standard status.

31 If you are on the provision list for committee members, send comments there. If you are not 32 on that list, subscribe to the [email protected] list and send 33 comments there. To subscribe, send an email message to provision-comment- 34 [email protected] with the word "subscribe" as the body of the message.

207212bb8d0cf1f11a2b881ca263fc19f.doc Page 1 of 158 35Copyright (C) OASIS Open 2005. All Rights Reserved.

307212bb8d0cf1f11a2b881ca263fc19f.doc Page 2 of 158 36Table of contents 371 Introduction...... 5 38 1.1 Purpose...... 5 39 1.2 Organization...... 5 40 1.3 Audience...... 5 41 1.4 Notation...... 6 42 1.4.1 Normative sections...... 6 43 1.4.2 Normative terms...... 6 44 1.4.3 Typographical conventions...... 6 45 1.4.4 Namespaces...... 7 462 Concepts...... 8 47 2.1 Domain Model...... 8 48 2.1.1 Requestor...... 8 49 2.1.2 Provider...... 9 50 2.1.3 Target...... 9 51 2.1.3.1 Target Schema...... 9 52 2.1.3.2 Supported Schema Entities...... 10 53 2.1.3.3 Capabilities...... 10 54 2.1.4 Provisioning Service Object (PSO)...... 10 55 2.2 Core Protocol...... 10 56 2.3 Profile...... 11 573 Protocol...... 12 58 3.1 Request/Response Model...... 12 59 3.1.1 Conversational flow...... 14 60 3.1.2 Status and Error codes...... 14 61 3.1.2.1 Status (normative)...... 14 62 3.1.2.2 Error (normative)...... 15 63 3.1.3 Synchronous and asynchronous operations...... 15 64 3.1.3.1 ExecutionMode attribute...... 16 65 3.1.3.2 Async Capability...... 16 66 3.1.3.3 Determining execution mode...... 17 67 3.1.3.4 Results of asynchronous operations (normative)...... 19 68 3.1.4 Individual and batch requests...... 19 69 3.2 Identifiers...... 20 70 3.2.1 RequestID (normative)...... 20 71 3.2.2 Target Identifier (normative)...... 21 72 3.2.3 PSO Identifier (normative)...... 21 73 3.3 Selection...... 23 74 3.3.1 QueryClauseType...... 23 75 3.3.2 Logical Operators...... 23 76 3.3.3 SelectionType...... 24 77 3.3.3.1 SelectionType in a Request (normative)...... 24 78 3.3.3.2 SelectionType Processing (normative)...... 25 79 3.3.3.3 SelectionType Errors (normative)...... 26 80 3.3.4 SearchQueryType...... 26 81 3.3.4.1 SearchQueryType in a Request (normative)...... 27 82 3.3.4.2 SearchQueryType Errors (normative)...... 28 83 3.4 Transactional Semantics...... 29 84 3.5 Operations...... 29 85 3.5.1 Core Operations...... 29 86 3.5.1.1 listTargets...... 29 87 3.5.1.2 add...... 39 88 3.5.1.3 lookup...... 44 89 3.5.1.4 modify...... 49

407212bb8d0cf1f11a2b881ca263fc19f.doc Page 3 of 158 90 3.5.1.5 delete...... 56 91 3.5.2 Async Capability...... 59 92 3.5.2.1 cancel...... 59 93 3.5.2.2 status...... 61 94 3.5.3 Batch Capability...... 66 95 3.5.3.1 batch...... 66 96 3.5.4 Bulk Capability...... 73 97 3.5.4.1 bulkModify...... 73 98 3.5.4.2 bulkDelete...... 75 99 3.5.5 Password Capability...... 78 100 3.5.5.1 setPassword...... 78 101 3.5.5.2 expirePassword...... 80 102 3.5.5.3 resetPassword...... 81 103 3.5.5.4 validatePassword...... 83 104 3.5.6 Reference Capability...... 86 105 3.5.6.1 Reference Definitions...... 88 106 3.5.6.2 References...... 89 107 3.5.6.3 Complex References...... 89 108 3.5.7 Search Capability...... 95 109 3.5.7.1 search...... 96 110 3.5.7.2 iterate...... 102 111 3.5.7.3 closeIterator...... 107 112 3.5.8 Suspend Capability...... 111 113 3.5.8.1 suspend...... 111 114 3.5.8.2 resume...... 113 115 3.5.8.3 active...... 115 116 3.6 Custom Capabilities...... 118 1174 Conformance (normative)...... 119 118 4.1 Core operations and schema are mandatory...... 119 119 4.2 Standard capabilities are optional...... 119 120 4.3 Custom capabilities...... 119 1215 Security and privacy considerations...... 120 122 5.1 Threat model...... 120 123 5.1.1 Unauthorized disclosure...... 120 124 5.1.2 Message Replay...... 120 125 5.1.2.1 Message insertion...... 120 126 5.1.2.2 Message deletion...... 120 127 5.1.2.3 Message modification...... 121 128 5.2 Safeguards...... 121 129 5.2.1 Authentication...... 121 130 5.2.2 Confidentiality...... 121 131 5.2.2.1 Communication confidentiality...... 121 132 5.2.2.2 Trust model...... 122 133 5.2.2.3 Privacy...... 122 134Appendix A. Core XSD...... 123 135Appendix B. Async Capability XSD...... 130 136Appendix C. Batch Capability XSD...... 132 137Appendix D. Bulk Capability XSD...... 134 138Appendix E. Password Capability XSD...... 136 139Appendix F. Reference Capability XSD...... 138 140Appendix G. Search Capability XSD...... 140 141Appendix H. Suspend Capability XSD...... 143 142Appendix I. Document References...... 145 143Appendix J. Acknowledgments...... 147 144Appendix K. Notices...... 148 145Appendix L. Revision history...... 149

507212bb8d0cf1f11a2b881ca263fc19f.doc Page 4 of 158 146

607212bb8d0cf1f11a2b881ca263fc19f.doc Page 5 of 158 7

1471 Introduction

1481.1 Purpose

149This specification defines the concepts and operations of an XML-based provisioning request-and- 150response protocol.

1511.2 Organization

152The body of this specification is organized into three major sections: Concepts, Protocol and 153Conformance. 154 The Concepts section introduces the main ideas in SPMLv2. Subsections highlight significant 155 features that later sections will discuss in more detail. 156 The Protocol section first presents an overview of protocol features and then discusses the 157 purpose and behavior of each protocol operation. The core operations are presented in an 158 order that permits a continuing set of examples. Subsequent sections present optional 159 operations. 160 161 Each section that describes an operation includes: 162 - The relevant XML Schema 163 - A normative subsection that describes the request for the operation 164 - A normative subsection that describes the response to the operation 165 - A non-normative sub-section that discusses examples of the operation 166 The Conformance section describes the aspects of this protocol that a requestor or provider 167 must support in order to be considered conformant. 168 A Security and privacy considerations section describes risks that an implementer of this 169 protocol should weigh in deciding how to deploy this protocol in a specific environment. 170Appendices contain additional information that supports the specification, including references to 171other documents.

1721.3 Audience

173The PSTC intends this specification to meet the needs of several audiences. 174One group of readers will want to know: "What is SPML?” 175A reader of this type should pay special attention to the Concepts section. 176A second group of readers will want to know: "How would I use SPML?" 177A reader of this type should read the Protocol section 178(with special attention to the examples). 179A third group of readers will want to know: "How must I implement SPML?" 180A reader of this type must read the Protocol section 181(with special attention to normative request and response sub-sections). 182A reader who is already familiar with SPML 1.0 will want to know: “What is new in SPMLv2?” 183A reader of this type should read the Concepts section thoroughly 184and also read the Appendix ?? which describes changes from SPML1.0 to SPMLv2.

807212bb8d0cf1f11a2b881ca263fc19f.doc Page 6 of 158 1851.4 Notation

1861.4.1 Normative sections

187Normative sections of this specification are labeled as such. The title of a normative section will 188contain the word “normative” in parentheses, as in the following title: “Syntax (normative)”.

1891.4.2 Normative terms

190This specification contains schema that conforms to W3C XML Schema and contains normative 191text that describes the syntax and semantics of XML-encoded policy statements. 192The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 193"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be 194interpreted as described in IETF RFC 2119 [RFC2119] 195 "they MUST only be used where it is actually required for interoperation or to limit 196 behavior which has potential for causing harm (e.g., limiting retransmissions)" 197These keywords are capitalized when used to unambiguously specify requirements of the protocol 198or application features and behavior that affect the interoperability and security of implementations. 199When these words are not capitalized, they are meant in their natural-language sense.

2001.4.3 Typographical conventions

201This specification uses the following typographical conventions in text: Format Description Indicates xmlName monospace font The name of an XML attribute, element or type.

“attributeName” monospace font An instance of an XML attribute. surrounded by double quotes

‘attributeValue’ monospace font A literal value (of type string). surrounded by double quotes

“attributeName=’value’ monospace font name An instance of an XML attribute value. ” followed by equals sign and value Read as “a value of (value) specified for surrounded by an instance of the (attributeName) single quotes attribute.” {XmlTypeName} monospace font The name of an XML type or surrounded by that is defined as part of SPMLv2. {ns:XmlTypeName} curly braces

or monospace font An instance of an XML element surrounded by <> that is defined as part of SPMLv2.

202Terms in italic bold-face are intended to have the meaning defined in the Glossary.

203Listings of SPML schemas appear like this.

907212bb8d0cf1f11a2b881ca263fc19f.doc Page 7 of 158 204

205Example code listings appear like this.

2061.4.4 Namespaces

207Conventional XML namespace prefixes are used throughout the listings in this specification to 208stand for their respective namespaces as follows, whether or not a namespace declaration is 209present in the example:

210 The prefix dsml: stands for the Directory Services Markup Language namespace [DSML].

211 The prefix xsd: stands for the W3C XML Schema namespace [XSD].

212 The prefix spml: stands for the SPMLv2 Core XSD namespace 213 [SPMLv2-CORE].

214 The prefix spmlasync: stands for the SPMLv2 Async Capability XSD namespace. [SPMLv2- 215 ASYNC].

216 The prefix spmlbatch: stands for the SPMLv2 Batch Capability XSD namespace 217 [SPMLv2-BATCH].

218 The prefix spmlbulk: stands for the SPMLv2 Bulk Capability XSD namespace 219 [SPMLv2-BULK].

220 The prefix spmlpass: stands for the SPMLv2 Password Capability XSD namespace 221 [SPMLv2-PASS].

222 The prefix spmlref: stands for the SPMLv2 Reference Capability XSD namespace 223 [SPMLv2-REF].

224 The prefix spmlsearch: stands for the SPMLv2 Search Capability XSD namespace 225 [SPMLv2-SEARCH].

226 The prefix spmlsuspend: stands for the SPMLv2 Suspend Capability XSD namespace 227 [SPMLv2-SUSPEND].

1007212bb8d0cf1f11a2b881ca263fc19f.doc Page 8 of 158 11

2282 Concepts

229SPML Version 2 (SPMLv2) builds on the concepts defined in SPML Version 1. 230The basic roles of Requesting Authority (RA) and Provisioning Service Provider (PSP) are 231unchanged. The core protocol continues to define the basis for interoperable management of 232Provisioning Service Objects (PSO). However, the concept of Provisioning Service Target (PST) 233has taken on new importance in SPMLv2.

2342.1 Domain Model

235The following section describes the main conceptual elements of the SPML domain model. The 236Entity Relationship Diagram (ERD) in Figure 1 shows the basic relationships between these 237elements.

RA PSP

PST

PSO

238 239 Figure 1. Domain model elements

2402.1.1 Requestor

241A Requesting Authority (RA) or requestor is a software component that issues well-formed SPML 242requests to a Provisioning Service Provider. Examples of requestors include: 243 Portal applications that broker the subscription of client requests to system resources 244 Service subscription interfaces within an Application Service Provider 245Trust relationship. In an end-to-end integrated provisioning scenario, any component that issues 246an SPML request is said to be operating as a requestor. This description assumes that the 247requestor and its provider have established a trust relationship between them. The details of 248establishing and maintaining this trust relationship are beyond the scope of this specification.

1207212bb8d0cf1f11a2b881ca263fc19f.doc Page 9 of 158 2492.1.2 Provider

250A Provisioning Service Provider (PSP) or provider is a software component that listens for, 251processes, and returns the results for well-formed SPML requests from a known requestor. For 252example, an installation of an Identity Management system could serve as a provider. 253Trust relationship. In an end-to-end integrated provisioning scenario, any component that 254receives and processes an SPML request is said to be operating as a provider. This description 255assumes that the provider and its requestor have established a trust relationship between them. 256The details of establishing and maintaining this trust relationship are beyond the scope of this 257specification.

2582.1.3 Target

259A Provisioning Service Target (PST) or target represents a destination or endpoint that a provider 260makes available for provisioning actions. 261A target is not a provider. A requestor asks a provider to act upon objects that the provider 262manages. Each target is a container for objects that a provider manages. 263A target may not be an actual endpoint. A target may represent a traditional user account source 264(such as a Windows NT domain or a directory service instance), or a target may represent an 265abstract collection of endpoints. 266Every provider exposes at least one target. Each target represents a destination or endpoint 267(e.g., a system, application or service—or a set of systems, applications, and services) to which the 268provider can provision (e.g., create or modify accounts). 269A target is a special, top-level object that: 270 A requestor can discover from the provider 271 No requestor can add, modify, delete or otherwise act upon 272 May contain any number of provisioning service objects (PSO) upon which a requestor may act 273 May contain a schema that defines the XML structure of the provisioning service objects (PSO) 274 that the target may contain 275 May define which schema entities the target supports 276 May expose capabilities: 277 - That apply to every supported schema entity 278 - That apply only to specific schema entities 279The SPMLv2 model does not restrict a provider’s targets other than to specify that: 280 A provider (PSP) must uniquely identify each target that it exposes. 281 A provider must uniquely identify each object (PSO) that a target contains. 282 Exactly one target must contain each object (PSO) that the provider manages.

2832.1.3.1 Target Schema

284The schema for each target defines the XML structure of the objects (PSO) that the target may 285contain. 286SPMLv2 does not specify a required format for the target schema. For example, a target schema 287could be XML Schema [XSD] or (a target schema could be) SPML1.0 Schema [SPMLv2-Profile- 288DSML]. 289Each target schema includes a schema namespace. The schema namespace indicates (to any 290requestor that recognizes the schema namespace) how to interpret the schema.

1307212bb8d0cf1f11a2b881ca263fc19f.doc Page 10 of 158 291A provider must present any object (to a requestor) as XML that is valid according to the schema of 292the target that contains the object. A requestor must accept and manipulate, as XML that is valid 293according to the schema of the target, any object that a target contains.

2942.1.3.2 Supported Schema Entities

295A target may declare that it supports only a subset of the entities (e.g., objectclasses or top-level 296elements) in its schema. A target that does not declare such a subset is assumed to support every 297entity in its schema. 298A provider must implement the basic SPML operations for objects on each target that are instances 299of each schema entity that the target supports.

3002.1.3.3 Capabilities

301A target may also expose a set of capabilities that it supports. Each capability defines optional 302operations or semantics. 303A capability must be either "standard" or "custom": 304 The OASIS PSTC defines each standard capability in an SPML namespace. 305 See the section entitled “Namespaces”. 306 Anyone may define a custom capability in another namespace. 307A target may support a capability for all of its supported schema entities or (a target may support a 308capability) only for specific subset of its supported schema entities. Each capability may specify 309any number of supported schema entities to which it applies. A capability that does not specify a 310supported schema entity is assumed to apply to every schema entity that the target supports. 311Optional operations. If a capability defines an optional operation and if the target supports that 312capability for a schema entity of which an object is an instance, then the provider must support that 313optional operation for that object. For example, if a target supports the Password Capability for 314User objects (but not for Group objects), then a requestor may ask the provider to perform the 315‘resetPassword’ operation for any User object (but the provider will fail any request to 316‘resetPassword’ for a Group).

3172.1.4 Provisioning Service Object (PSO)

318A Provisioning Service Object (PSO), sometimes simply called an object, represents a data entity 319or an information object on a target. For example, a provider would represent each account that 320the provider manages as an object. 321NOTE: Within this document, the term “object” (unless otherwise qualified) refers to a PSO. 322Every object is contained by exactly one target. Each object has a unique identifier (PSO-ID).

3232.2 Core Protocol

324SPMLv2 retains the SPML1.0 concept of a “core protocol”. The SPMLv2 Core XSD defines: 325 Basic operations (such as ‘add’, ’modify’ and ‘delete’) 326 Basic and extensible data elements 327 The means to expose individual targets and optional operations 328The SPMLv2 Core XSD also defines modal mechanisms that allow a requestor to: 329 Specify that a requested operation must be executed asynchronously 330 (or to specify that a requested operation must be executed synchronously)

1407212bb8d0cf1f11a2b881ca263fc19f.doc Page 11 of 158 331 Recognize that a provider has chosen to execute an operation asynchronously 332 Obtain the status of an asynchronous request 333 Cancel an asynchronous request 334Conformant SPMLv2 implementations must support the core protocol, including: 335 The new ‘listTargets’ operation 336 The basic operations for every schema entity that a target supports 337 The modal mechanisms for asynchronous operations 338(For more information, see the section entitled “Conformance”).

3392.3 Profile

340SPMLv2 defines two “profiles” in which a requestor and provider may exchange SPML protocol: 341 XML Schema as defined in the “SPMLv2 XSD Profile” [SPMLv2-Profile-XSD]. 342 DSMLv2 as defined in the “SPMLv2 DSMLv2 Profile” [SPMLv2-Profile-DSML]. 343A requestor and a provider may exchange SPML protocol in any profile to which they agree. 344SPML 1.0 defined file bindings and SOAP bindings that assumed the SPML1.0 Schema for DSML 345[SPML-Bind]. The SPMLv2 DSMLv2 Profile provides a degree of backward compatibility with 346SPML 1.0. The DSMLv2 profile supports a schema model similar to that of SPML 1.0. 347The DSMLv2 Profile may be more convenient for applications that access mainly targets that are 348LDAP or X500 directory services. The XSD Profile may be more convenient for applications that 349access mainly targets that are web services.

1507212bb8d0cf1f11a2b881ca263fc19f.doc Page 12 of 158 16

3503 Protocol

351The general model adopted by this protocol is that a requestor (client) asks a provider (server) to 352perform operations. In the simplest case, each request for an SPML operation is processed 353individually and is processed synchronously. The “Request/Response Model” section below 354presents this general model and discusses mechanisms that govern asynchronous execution. The 355Identifiers and Selection sections also describe aspects (of the protocol) that apply to many 356operations. 357In order to encourage adoption of this standard, this specification minimizes the set of operations 358that a provider must implement. The Core Operations section discusses these required operations. 359This specification also defines optional operations. Some operations are optional (rather than 360required) because the operations may be more difficult for a provider to implement for certain kinds 361of targets. Some operations are optional because the operations may apply only to specific types of 362objects on a target. This specification defines a set of standard capabilities, each of which groups 363optional operations that are functionally related. The remainder of the Operations section discusses 364optional operations (such as search) that are associated with SPMLv2’s standard capabilities. 365The capability mechanism in SPMLv2 is open and allows an individual provider (or any third party) 366to define additional custom capabilities. See Custom Capabilities later in this section.

3673.1 Request/Response Model

368The general model adopted by this protocol is that a requestor (client) asks a provider (server) to 369perform an operation. A requestor asks a provider to perform an operation by sending to the 370provider an SPML request that describes the operation. The provider examines the request and, if 371the provider determines that the request is valid, the provider does whatever is necessary to 372implement the requested operation. The provider also returns to the requestor an SPML response 373that details any status or error that pertains to the request.

1707212bb8d0cf1f11a2b881ca263fc19f.doc Page 13 of 158

1807212bb8d0cf1f11a2b881ca263fc19f.doc Page 14 of 158 use="required"/>

374The following subsections describe aspects of this request/response model in more detail: 375 the exchange of requests and responses between requestor and provider 376 synchronous and asynchronous execution of operations 377 individual and batch requests

3783.1.1 Conversational flow 379A requestor asks a provider to do something by issuing an SPML request. A provider responds 380exactly once to each request. Therefore, the simplest conversation (i.e., pattern of exchange) 381between a requestor and a provider is an orderly alternation of request and response. However, the 382SPML protocol does not require this. A requestor may issue any number of concurrent requests to 383a single provider. A requestor may issue any number of concurrent requests to multiple providers. 384Recommend requestID. Each SPML request should specify a reasonably unique identifier as the 385value of “requestID”. See “Request Identifier (normative)”. This allows a requestor to control the 386identifier for each requested operation and (also allows the requestor) to match each response to 387the corresponding request without relying on the transport protocol that underlies the SPML 388protocol exchange.

3893.1.2 Status and Error codes

390A provider’s response always specifies a “status”. This value tells the requestor what the 391provider did with (the operation that was described by) the corresponding request. 392If a provider’s response specifies “status=’failure’”, then the provider’s response must also specify 393an “error”. This value tells the requestor what type of problem prevented the provider from 394executing (the operation that was described by) the corresponding request.

395The “status” and “error” attributes of a response apply to (the operation that is described by) 396the corresponding request. This is straightforward for most requests. The status and batch 397operations present the only subtleties. 398 A status request asks for the status of another operation that the provider is already executing 399 asynchronously. See “Synchronous and asynchronous operations” below. A status response 400 has status and error attributes that tell the requestor what happened to the status request itself. 401 However, the response to a successful status operation also contains a nested response that 402 tells what has happened to the operation that the provider is executing asynchronously. 403 A batch request contains nested requests (each of which describes an operation). The 404 response to a batch request contains nested responses (each of which corresponds to a 405 request that was nested in the batch request). See “Individual and batch requests” below.

4063.1.2.1 Status (normative)

407A provider’s response MUST specify “status” as one of the following values: ‘success’, 408‘failure’ or ‘pending’.

1907212bb8d0cf1f11a2b881ca263fc19f.doc Page 15 of 158 409 A response that specifies “status=’success’” 410 indicates that the provider has completed the requested operation. 411 In this case, the response contains any result of the operation 412 and the response MUST NOT specify “error” (see below).

413 A response that specifies “status=’failure’” 414 indicates that the provider could not complete the requested operation. 415 In this case, the response MUST specify an appropriate value of “error” (see below).

416 A response that specifies “status=’pending’” 417 indicates that the provider will execute the requested operation asynchronously 418 (see “Synchronous and asynchronous operations” below). 419 In this case, the response acknowledges the request and contains the “requestID” value 420 that identifies the asynchronous operation.

4213.1.2.2 Error (normative)

422A response that specifies “status=’failure’” MUST specify an appropriate value of “error”:

423 A response that specifies “error=’malformedRequest’” 424 indicates that the provider could not interpret the request. 425 This includes, but is not limited to, parse errors.

426 A response that specifies “error=’unsupportedOperation’” 427 indicates that the provider does not support the operation that the request specified.

428 A response that specifies “error=’unsupportedIdentifierType’” 429 indicates that the provider does not support the type of identifier specified in the request.

430 A response that specifies “error=’noSuchIdentifier’” 431 indicates that the provider (supports the type of identifier specified in the request, 432 but the provider) cannot find the object to which an identifier refers.

433 A response that specifies “error=’unsupportedExecutionMode’” 434 indicates that the provider does not support the requested mode of execution.

435 A response that specifies “error=’invalidContainment’” 436 indicates that the provider cannot add the specified object to the specified container. 437 - The request may not specify a valid container--especially if the request specifies 438 as the container an object on the target (rather than the target itself). 439 The target schema implicitly or explicitly declares each supported schema entity. 440 An explicit declaration of a supported schema entity specifies whether an instance 441 of that schema entity may contain other objects. 442 - The request may have specified a container that is not valid for the specified object. 443 The target (or a system or application that underlies the target) may restrict the types of 444 objects that the provider can add to the specified container. The target (or a system or 445 application that underlies the target) may restrict the containers to which the provider can 446 add the specified object.

447 A response that specifies “error=’customError’” indicates that the provider has 448 encountered an error that none of the standard error code values describes. 449 In this case, the provider’s response SHOULD provide error information in a format that is 450 available to the requestor. SPMLv2 does not specify the format of a custom error.

2007212bb8d0cf1f11a2b881ca263fc19f.doc Page 16 of 158 4513.1.3 Synchronous and asynchronous operations

452A provider may execute a requested operation either synchronously or asynchronously. 453 Synchronous: operation before response. If a provider executes a requested operation 454 synchronously, the provider completes the requested operation before the provider returns a 455 response to the requestor. The response will include the status and any error or result. 456 Asynchronous: response before operation. If a provider executes a requested operation 457 asynchronously, the provider returns to the requestor a response (that indicates that the 458 operation will be executed asynchronously) before the provider executes the requested 459 operation. The response will specify “status=’pending’” and will specify a “requestID” 460 value that the requestor must use in order to cancel the asynchronous operation or (in order to) 461 obtain the status or results of the asynchronous operation.

462 - If a request specifies “requestID”, then the provider’s response to that request will 463 specify the same “requestID” value. 464 Requestor Provider REQUEST requestID=1

RESPONSE requestID=1 status=”pending”

465 - If the request omits “requestID”, then the provider’s response to that will specify a 466 “requestID” value that is generated by the provider. 467 Requestor REQUEST Provider

RESPONSE requestID=9 status=”pending”

468A requestor may specify the execution mode for an operation in its request or (a requestor may 469omit the execution mode and thus) allow the provider to decide the execution mode (for the 470requested operation). If the requestor specifies an execution mode that the provider cannot support 471for the requested operation, then the provider will fail the request.

4723.1.3.1 ExecutionMode attribute

473A requestor uses the optional “executionMode” attribute of an SPML request to specify that the 474provider must execute the specified operation synchronously or (to specify that the provider must 475execute the specified operation) asynchronously. If a requestor omits the “executionMode” 476attribute from an SPML request, the provider decides whether to execute the requested operation 477synchronously or (to execute the requested operation) asynchronously.

4783.1.3.2 Async Capability

479A provider uses the Async Capability that is defined as part of SPMLv2 to tell any requestor that the 480provider supports asynchronous execution of requested operations on objects contained by that 481target. A target may further refine this declaration to apply only to specific types of objects (i.e., for a 482specific subset of supported schema entities) on the target. 483SPMLv2’s Async Capability also defines two operations that a requestor may use to manage other 484operations that a provider is executing asynchronously:

2107212bb8d0cf1f11a2b881ca263fc19f.doc Page 17 of 158 485 A ‘status’ operation allows a requestor to check the status (and optionally results) of an 486 operation (or of all operations) 487 A ‘cancel’ operation asks the provider to stop executing an operation. 488For more information, see the Async Capability section.

4893.1.3.3 Determining execution mode

490By default, a requestor allows a provider to decide whether to execute a requested operation 491synchronously or asynchronously. A requestor that needs the provider to execute a requested 492operation in a particular manner must specify this in the request. Each subsection that follows 493describes one of the four possibilities: 494 Requestor specifies synchronous execution 495 Requestor specifies asynchronous execution 496 Provider chooses synchronous execution 497 Provider chooses asynchronous execution 498The following subsections normatively apply to every SPMLv2 operation unless the normative text 499that describes an operation specifies otherwise.

5003.1.3.3.1 Requestor specifies synchronous execution (normative)

501A requestor MAY specify that an operation must execute synchronously. A requestor that wants the 502provider to execute an operation synchronously MUST specify 503“executionMode=‘synchronous’“ in the SPML request. 504If a requestor specifies that an operation must be executed synchronously and the provider cannot 505execute the requested operation synchronously, then the provider MUST fail the operation. If a 506provider fails an operation because the provider cannot execute the operation synchronously, then 507the provider’s response MUST specify “status=’failed’” and 508“error=’unsupportedExecutionMode’”. 509If a requestor specifies that an operation must be executed synchronously and the provider does 510not fail the request, then the provider implicitly agrees to execute the requested operation 511synchronously. The provider MUST acknowledge the request with a response that contains any 512status and any error or output of the operation. The provider’s response MUST NOT specify 513“status=’pending’”. The provider’s response MUST specify either “status='success'” or 514“status=’failed’”.

515 If the provider’s response specifies “status=’failed’”, then the provider’s response must 516 have an “error” attribute.

517 If the provider’s response specifies “status='success'”, then the provider’s response MUST 518 contain any additional results (i.e., output) of the completed operation.

5193.1.3.3.2 Requestor specifies asynchronous execution (normative)

520A requestor may specify that an operation must execute asynchronously. A requestor that wants 521the provider to execute an operation asynchronously MUST specify 522“executionMode=‘asynchronous’” in the SPML request. 523If a requestor specifies that an operation must be executed asynchronously and the provider cannot 524execute the requested operation asynchronously, then the provider MUST fail the operation. If the 525provider fails the operation because the provider cannot execute the operation asynchronously,

2207212bb8d0cf1f11a2b881ca263fc19f.doc Page 18 of 158 526then the provider’s response MUST specify “status=’failed’” and (the provider’s response 527MUST specify) “error=’unsupportedExecutionMode’”. 528If a requestor specifies that an operation must be executed asynchronously and the provider does 529not fail the request, then the provider implicitly agrees to execute the requested operation 530asynchronously. The provider MUST acknowledge the request with a synchronous response that 531indicates that the operation will execute asynchronously. The provider’s response MUST specify 532“status=’pending’” and (the provider’s response MUST specify) “requestID=’’”.

533 If the request specifies a “requestID” value, then the provider’s response MUST specify the 534 same “requestID” value.

535 If the request omits “requestID”, then the provider’s response MUST specify a 536 “requestID” value that uniquely identifies the requested operation within the namespace of 537 the provider. 538If the provider’s response indicates that the requested operation will execute asynchronously, the 539requestor may continue with other processing. If the requestor wishes to obtain the status and 540results of the requested operation (or to cancel the requested operation), the requestor MUST use 541the “requestID” value that is returned in the provider’s response to identify the operation. 542See also the sections entitled “Async Capability” and “Results of asynchronous operations 543(normative)”.

5443.1.3.3.3 Provider chooses synchronous execution (normative)

545A requestor MAY allow the provider to decide whether to execute a requested operation 546synchronously or asynchronously. A requestor that wants to let the provider decide the type of 547execution for an operation MUST omit the “executionMode” attribute of the SPML request. 548If a requestor lets the provider decide the type of execution for an operation and the provider 549chooses to execute the requested operation synchronously, then the provider’s response MUST 550indicate that the requested operation was executed synchronously. The provider’s response MUST 551NOT specify “status=’pending’”. The provider’s response MUST specify either 552“status='success'” or “status=’failed’”.

553 If the provider’s response specifies “status=’failed’”, then the provider’s response must 554 have an “error” attribute.

555 If the provider’s response specifies “status='success'”, then the provider’s response MUST 556 contain any additional results (i.e., output) of the completed operation.

5573.1.3.3.4 Provider chooses asynchronous execution (normative)

558A requestor MAY allow a provider to decide whether to execute a requested operation 559synchronously or asynchronously. A requestor that wants to let the provider decide the type of 560execution for an operation MUST omit the “executionMode” attribute of the SPML request. 561If a requestor lets the provider decide the type of execution for an operation and the provider 562chooses to execute the requested operation asynchronously, then the provider’s response must 563indicate that the the requested operation will execute asynchronously. The provider MUST 564acknowledge the request with a response that indicates that the operation will execute 565asynchronously. The provider’s response MUST specify “status=’pending’” and (the provider’s 566response MUST specify) “requestID=’’”.

2307212bb8d0cf1f11a2b881ca263fc19f.doc Page 19 of 158 567 If the request specifies a “requestID” value, then the provider’s response MUST specify the 568 same “requestID” value.

569 If the request omits “requestID”, then the provider’s response MUST specify a 570 “requestID” value that uniquely identifies the requested operation within the namespace of 571 the provider. 572If the provider’s response indicates that the requested operation will execute asynchronously, the 573requestor may continue with other processing. If the requestor wishes to obtain the status and 574results of the requested operation (or to cancel the requested operation), the requestor MUST use 575the “requestID” value that is returned in the provider’s response to identify the operation. 576See also the sections entitled “Async Capability” and “Results of asynchronous operations 577(normative)”.

5783.1.3.4 Results of asynchronous operations (normative)

579A provider that supports asynchronous execution of requested operations MUST maintain the 580status and results of each asynchronously executed operation during the period of time that the 581operation is executing and for some reasonable period of time after the operation completes. 582Maintaining this information allows the provider to respond to status requests. 583A provider that supports asynchronous execution of requested operations SHOULD publish out-of- 584band (i.e., make available to requestors in a manner that is not specified by this document) any limit 585on the how long after the completion of an asynchronous operation the provider will keep the status 586and results of that operation.

5873.1.4 Individual and batch requests

588A requestor generally requests each operation individually. SPMLv2 also defines a capability to 589batch requests. If the provider supports this batch capability, a requestor may group any number of 590requests (e.g., requests to ‘add’, ‘modify’ or ‘delete’) into a single request. 591Individual. The SPMLv2 core protocol allows a requestor to ask a provider to execute an individual 592operation. Each request that is part of the SPMLv2 Core XSD asks a provider to perform a single 593operation. 594Batch. SPMLv2 defines ‘batch’ as an optional operation that allows a requestor to combine any 595number of requests into a single request. See the Batch Capability section.

2407212bb8d0cf1f11a2b881ca263fc19f.doc Page 20 of 158 5963.2 Identifiers

597SPMLv2 uses several different types of identifiers.

598 An instance of {xsd:string} identifies a target. 599 A target identifier must be unique within the (namespace of the) provider.

600 An instance of {xsd:ID} identifies a request or an operation.

601 An instance of {PSOIdentifierType} identifies an object on a target. 602 An instance of {PSOIdentifierType} combines a target identifier with an object identifier. 603 The target identifier MUST be unique within the (namespace of the) provider. 604 The object identifier MUST be unique within the (namespace of the) target.

6053.2.1 RequestID (normative)

606RequestID in a request. A requestor SHOULD specify a reasonably unique value for the 607“requestID” attribute in each request. A requestID value need not be globally unique. A 608requestID value needs only to be sufficiently unique to identify each outstanding request. (That is, a 609requestor SHOULD specify as the value of “requestID” in each SPML request a value that is 610sufficiently unique to identify each request for which the requestor has not yet received the 611corresponding response.) 612A requestor that uses a transport protocol that is synchronous (such as SOAP/HTTP) MAY omit 613“requestID”. The synchronous nature of the transport protocol exchange itself ensures that the 614requestor can match the provider’s response to the request. (The provider’s response will contain 615any requestID that is necessary—for example, because the provider executes the requested 616operation asynchronously. See “RequestID in a response” immediately below.) 617RequestID in a response. A provider’s response to a request that specifies “requestID” MUST 618specify the same “requestID” value.

619A provider’s response to a request that does not specify a value for “requestID” MAY omit the 620“requestID” attribute UNLESS the provider executes the requested operation asynchronously.

2507212bb8d0cf1f11a2b881ca263fc19f.doc Page 21 of 158 621If the provider executes asynchronously (the operation that was described by) a request that 622omitted “requestID”, then the provider MUST generate a value that uniquely identifies the 623operation to the provider and (the provider MUST) specify this value as the value of the 624“requestID” attribute in the provider’s response. (This allows the requestor to cancel or to obtain 625the status of the operation that the provider is executing asynchronously. See Async Capability.)

6263.2.2 Target Identifier (normative)

627Each of a provider’s targets has a string identifier. Within a provider’s listTargets response, the 628“targetID” attribute of each element specifies this identifier.

629TargetId is unique within provider. Each in a provider’s 630MUST specify a value for “targetID” that uniquely identifies the target within the namespace of 631the provider. 632Wherever targetID occurs in a request or in a response, the targetID must correspond to one of 633the provider’s targets. (That is, the value of any “targetID” attribute that a request specifies or 634(that a request) indirectly contains MUST match the value of the “targetID” attribute that a 635 element in the provider’s specifies.) 636If a request contains an invalid targetID, the provider’s response MUST specify 637“error=’noSuchIdentifier’”.

6383.2.3 PSO Identifier (normative)

639PSO Identifier must be unique. A provider MUST ensure that each object’s PSO-ID is unique 640(within the namespace of the provider). Since every instance of {PSOIdentifierType} also 641specifies the target that contains the object (see the next topic immediately below), the value that 642identifies an object must be unique within the namespace of the target.

643TargetID. Any instance of {PSOIdentifierType} MAY specify “targetID”.

644 If the provider's contains only one , 645 then an instance of {PSOIdentifierType} MAY omit "targetID".

646 If the provider's contains more than one , 647 then any instance of {PSOIdentifierType} MUST specify "targetID". 648 The value of “targetID” MUST identify a valid target. (That is, the value of “targetID” 649 MUST match the “targetID” of a in the provider’s . 650 See the section entitled “Target Identifier (normative)” above.)

651containerID. Any instance of {PSOIdentifierType} MAY contain at most one 652. Any MUST identify an existing object that exists on the target. 653(That is, the content of any in an instance of {PSOIdentifierType} MUST 654match the of an object that exists on a target. In addition, the value of any "targetID" 655attribute in the element MUST match the value of the "targetID" attribute of the 656instance of {PSOIdentifierType} that contains the .)

657ID. Any instance of {PSOIdentifierType} MAY specify “ID”. This depends on the profile that 658the requestor and provider have agreed to use. 659 The DSML Profile and the XML Schema Profile both specify that an instance of 660 {PSOIdentifierType} MUST specify "ID". The value of “ID” MUST uniquely identify an 661 object within the namespace of the target that “targetID” specifies.

2607212bb8d0cf1f11a2b881ca263fc19f.doc Page 22 of 158 662 Another profile may specify that an instance of {PSOIdentifierType} MAY omit "ID".

663Content depends on profile. The content of an instance of {PSOIdentifierType} depends on 664the profile that a requestor and provider agree to use. 665 Both the DSML profile and the XML Schema Profile specify that an instance of 666 {PSOIdentifierType} MUST have an "ID" attribute (see the topic immediately above). 667 Neither the DSML profile nor the XML Schema Profile specifies the content of an instance of 668 {PSOIdentifierType}.

669 Another profile may specify the content of an instance of {PSOIdentifierType}. 670Caution: PSO Identifier is mutable. A provider MAY change the PSO-ID for an object. For 671example, moving an organizational unit (OU) beneath a new parent within a directory service will 672change the distinguished name (DN) of the organizational unit. If the provider exposes the 673directory service DN as the object’s PSO-ID, then this operation will change the object’s PSO-ID. 674Recommend immutable PSO Identifier. A provider SHOULD expose an immutable value (such 675as a globally unique identifier or “guid”) as the PSO-ID for each object.

2707212bb8d0cf1f11a2b881ca263fc19f.doc Page 23 of 158 6763.3 Selection

6773.3.1 QueryClauseType

678SPMLv2 defines a {QueryClauseType} that is used to select objects. Each instance of 679{QueryClauseType} represents a selection criterion.

680{QueryClauseType} specifies no element or attribute. This type is a semantic marker. 681 Any capability may define elements of (types that extend) QueryClauseType. These 682 queryClauses allow a requestor to search for objects based on capability-specific data. 683 (For example, the SPML Reference Capability defines a element that 684 enables a requestor to query for objects that have a specific reference. 685 The SPML Suspend Capability defines an element that enables a requestor to 686 query for objects that are enabled or disabled.) 687 An instance of {SelectionType}, which extends {QueryClauseType}, may filter a set of 688 objects. {SelectionType} may also be used to specify a particular element or attribute of an 689 object. See the section entitled “SelectionType” below. 690 The SPMLv2 Search Capability defines three logical operators that indicate how a provider 691 should combine selection criteria. Each logical operator is an instance of 692 {LogicalOperatorType}, which extends {QueryClauseType}. 693 See the section entitled “Logical Operators” below.

6943.3.2 Logical Operators

695The SPMLv2 Search Capability defines three logical operators that indicate how a provider should 696combine selection criteria. 697 The logical operator specifies a conjunct 698 (that is, the is true if and only if every selection criterion that the contains is true). 699 The logical operator specifies a disjunct 700 (that is, the is true if any selection criterion that the contains is true). 701 The logical operator specifies negation 702 (that is, the is true if and only if the selection criterion that the contains is false.)

2807212bb8d0cf1f11a2b881ca263fc19f.doc Page 24 of 158

7033.3.3 SelectionType

704SPMLv2 defines a {SelectionType} that is used in two different ways: 705 An instance of {SelectionType} may specify an element or attribute of an object. 706 For example, the of a specifies the part of an object that a 707 modify operation (or a bulkModify operation) will change. 708 An instance of {SelectionType} may filter a set of objects. 709 For example, a may contain a that restricts, based on the schema-defined 710 XML representation of each object, the set of objects that a search operation returns 711 (or that a bulkModify operation changes or that a bulkDelete operation deletes).

712SelectionType. An instance of {SelectionType} has a “path” attribute which value is an 713expression. An instance of {SelectionType} also contains a “namespaceURI” attribute that 714indicates (to any provider that recognizes the namespace) the language in which the value of the 715“path” attribute is expressed.

716Namespace Prefix Mappings. An instance of {SelectionType} may also contain any number 717of elements (see the normative section that follows next). Each 718 allows a requestor to specify the URI of an XML namespace for a 719namespace prefix that occurs (or that may occur) in the value of the “path” attribute.

7203.3.3.1 SelectionType in a Request (normative)

721namespaceURI. An instance of {SelectionType} MUST have a “namespaceURI” attribute. 722The value of the “namespaceURI” attribute MUST specify the XML namespace of a query 723language. (The value of the “path” attribute must be an expression that is valid in this query 724language—see below.)

725path. An instance of {SelectionType} MUST have a “path” attribute. The value of the “path” 726attribute MUST be an expression that is valid in the query language that the “namespaceURI” 727attribute specifies. The “path” value serves different purposes in different contexts.

2907212bb8d0cf1f11a2b881ca263fc19f.doc Page 25 of 158 728 Within a element, the value of the “path” attribute MUST specify a target 729 schema entity (i.e., an element or attribute) of the object that the provider is to modify.

730 Within a element, the value of the“path” attribute MUST specify a filter that selects 731 objects based on: 732 - The presence (or absence) of a specific element or attribute 733 - The presence (or absence) of a specific value in the content of an element 734 or (the presence of absence of a specific value) in the value of an attribute

735The value of the “path” attribute MUST be expressed in terms of elements or attributes that are 736valid (according to the schema of the target) for the type of object on which the provider is 737requested to operate.

738Namespace prefix mappings. An instance of {SelectionType} MAY contain any number of 739 elements.

740 Each MUST have a “prefix” attribute whose value specifies a 741 namespace prefix (that may occur in the filter expression that is the value of the “path” 742 attribute).

743 Each MUST have a “namespace” attribute whose value is the URI 744 for an XML namespace. 745A requestor SHOULD use these mappings to define any namespace prefix that the (value of the) 746“path” attribute contains.

7473.3.3.2 SelectionType Processing (normative)

748A provider MUST evaluate an instance of {SelectionType} in a manner that is appropriate to 749the context in which the instance of {SelectionType} occurs:

750 Within a element, a provider must resolve the value of the “path” attribute 751 to a schema entity (i.e., to an element or attribute) of the object that the provider is to modify.

752 Within a element, a provider must evaluate the value of the “path” attribute as a 753 filter expression that selects objects based on: 754 - The presence (or absence) of a specific element or attribute 755 - The presence (or absence) of a specific value in the content of an element 756 or (the presence of absence of a specific value) in the value of an attribute 757Namespace prefix mappings. A provider SHOULD use any instance of 758 that an instance of {SelectionType} contains in order to resolve any 759namespace prefix that the value of the “path” attribute contains.

3007212bb8d0cf1f11a2b881ca263fc19f.doc Page 26 of 158 7603.3.3.3 SelectionType Errors (normative)

761A provider’s response (to a request that contains an instance of {SelectionType}) MUST 762specify an error if any of the following is true:

763 The provider does not recognize the value of the “namespaceURI” attribute as indicating an 764 expression language that the provider supports.

765 The provider does not recognize the value of the “path” attribute as an expression that is 766 valid in the language that the “namespaceURI” attribute specifies.

767 The provider does not recognize the value of a “path” attribute as an expression that refers to 768 a schema entity (i.e., element or attribute) that is valid according to the schema of the target. 769 The provider does not support the expression that SelectionType#path specifies. 770 (For example, the expression may be too complex or the expression may contain syntax that 771 the provider does not support.) 772In all of the cases described above, the provider’s response MUST specify either 773"error='unsupportedSelectionType'" or “error=’customError’”. 774 In general, the provider’s response SHOULD specify 775 “error=’unsupportedSelectionType’”. The provider’s response MAY also contain 776 instances of that describe more specifically the problem with the request.

777 However, a provider’s response MAY specify “error=’customError’” 778 if the provider is able to indicate more specifically the problem with the request.

7793.3.4 SearchQueryType

780SPMLv2 defines a {SearchQueryType} that is used to select objects on a target.

Open content is one or more instances of QueryClauseType (including SelectionType) or LogicalOperator.

781targetID specifies the target on which to search for objects.

3107212bb8d0cf1f11a2b881ca263fc19f.doc Page 27 of 158 782basePsoID specifies the starting point for a query. Any MUST identify an existing 783object to use as a base context or “root” for the search. That is, a that contains 784 may select only the specified container and objects in that container. 785Scope indicates whether the query should select the container itself, objects directly contained, or 786any object directly or indirectly contained.

787The “scope” attribute restricts the search operation to one of the following: 788 To the base context itself. 789 To the base context and its direct children. 790 To the base context and any of its descendants.

7913.3.4.1 SearchQueryType in a Request (normative)

792targetID. A MAY specify “targetID”. 793 If the provider's contains only one , 794 then a requestor MAY omit the “targetID” attribute of {searchQueryType}. 795 If the provider's contains more than one , 796 then a requestor MUST specify the “targetID” attribute of {searchQueryType}.

797basePsoID. A MAY contain at most one . 798 A requestor that wants to search the entire namespace of a target 799 MUST NOT supply . 800 A requestor that wants to search beneath a specific object on a target 801 MUST supply . Any MUST identify an object that exists on the 802 target. (That is, any MUST match the of an object that already exists 803 on the target.)

804scope. A MAY have a “scope” attribute. The value of the “scope” attribute specifies the 805set of objects against which the provider should evaluate the

element:

806 A requestor that wants the provider to search only the object identified by 807 MUST specify “scope=’pso’”. (NOTE: It is an error to specify "scope='pso'" in a 808 that does not contain . The target is not an object.) 809 See the section below entitled “SearchQueryType Errors (normative)”. 810 A requestor that wants the provider to search only direct descendants of the target or (that 811 wants to search only direct descendants) of the object specified by MUST 812 specify “scope=’oneLevel’”. 813 A requestor that wants the provider to search any direct or indirect descendant of the target or 814 (that wants to search any direct or indirect descendant) of the object specified by 815 MUST specify “scope=’subTree’”.

816Open content. A MUST contain (as open content) exactly one instance of a type that 817extends {QueryClauseType}.

818 Any capability may define elements of (a type that extends) {QueryClauseType}. These 819 elements allow a requestor to select objects based on capability-defined data. 820 See the section entitled "QueryClauseType" above.

821 A element is an instance of {SelectionType} which extends {QueryClauseType} 822 to filter objects based on schema-defined content. See the section entitled “SelectionType in a 823 Request (normative)“.

3207212bb8d0cf1f11a2b881ca263fc19f.doc Page 28 of 158 824 Logical Operators such as , and combine individual selection criteria. 825 A logical operator MUST contain at least one instance of a type that extends 826 {QueryClauseType} or a (logical operator MUST contain at least one) logical operator. 827 See the section entitled "Logical Operators" above.

8283.3.4.2 SearchQueryType Errors (normative)

829The response to a request that contains a (i.e., an instance of {SearchQueryType}) 830MUST specify an appropriate value of “error” if any of the following is true:

831 If the in a specifies “scope=’pso’” but does not contain 832 . (The target itself is not a PSO.)

833 If the "targetID" of the does not specify a valid target.

834 A specifies "targetID" and (the also) contains , but the 835 value of "targetID" in the does not match the value of "targetID" in the 836 "basePsoID".

837 A contains a that does not identify an object that exists on a target. 838 (That is, the does not match the of any object that exists on a target.) 839 If the provider cannot evaluate an instance of {QueryClauseType} that the contains. 840 If the open content of the is too complex for the provider to evaluate. 841 If the open content of the contains a syntactic error 842 (such as an invalid structure of logical operators or query clauses). 843 If the provider does not recognize an element of open content that the contains. 844Also see the section entitled "SelectionType Errors (normative)".

3307212bb8d0cf1f11a2b881ca263fc19f.doc Page 29 of 158 8453.4 Transactional Semantics

846SPMLv2 specifies no transactional semantics. This specification defines no operation that implies 847atomicity. At the time of this writing, no core operation and no operation defined by one of 848SPMLv2’s standard capabilities defines a logical unit of work that can be committed or rolled back 849as a unit. 850Provisioning operations are notoriously difficult to undo and redo. For security reasons, many 851systems and applications will not allow certain identity management operations to be fully reversed 852or repeated. (More generally, support for transactional semantics suggests participation in 853externally managed transactions. These protocols are beyond the scope of this specification.) 854Any transactional semantics should be defined as a capability (or possibly as more than one 855capability). See the section entitled “Custom Capabilities”. A transactional capability would define 856optional operations that imply atomicity or allow the requestor to specify atomicity. 857Any provider that is able to support transactional semantics should then declare its support for such 858a capability as part of the provider’s response to the listTargets operation (as the provider would 859declare its support for any other capability).

8603.5 Operations

861The first subsection discusses the required Core Operations. 862Subsequent subsections discuss any optional operation that is associated with each of the standard 863capabilities: 864 Async Capability 865 Batch Capability 866 Bulk Capability 867 Password Capability 868 Reference Capability 869 Search Capability 870 Suspend Capability

8713.5.1 Core Operations

872Schema syntax for the SPMLv2 core operations is defined in a schema associated with the 873following XML namespace: urn:oasis:names:tc:SPML:2:0 [SPMLv2-CORE]. The Core XSD 874is included as Appendix A to this document.

875A conformant provider must implement all the operations defined in the Core XSD. For more 876information, see the section entititled Conformance. 877The SPMLv2 core operations include: 878 a discovery operation (listTargets) on the provider 879 several basic operations (add, lookup, modify, delete) that apply to objects on a target

8803.5.1.1 listTargets

881The listTargets operation enables a requestor to determine the set of targets that a provider makes 882available for provisioning and (the listTargets operation also enables a requestor) to determine the 883set of capabilities that the provider supports for each target. 884The subset of the Core XSD that is most relevant to the listTargets operation follows.

3407212bb8d0cf1f11a2b881ca263fc19f.doc Page 30 of 158

3507212bb8d0cf1f11a2b881ca263fc19f.doc Page 31 of 158 type="spml:CapabilitiesListType" minOccurs="0" maxOccurs="1"/>

885ListTargets must be synchronous. Because the requestor cannot know (at the time the requestor 886asks to listTargets) whether the provider supports asynchronous execution, the ‘listTargets’ 887operation must be synchronous. 888ListTargets is not batchable. Because the requestor cannot know (at the time the requestor asks 889the provider to listTargets) whether the provider supports the batch capability, a requestor must not 890nest a ‘listTargets’ request in a batch request.

8913.5.1.1.1 Request (normative)

892A requestor MUST send a to a provider in order to ask the provider to 893declare the set of targets that the provider exposes for provisioning operations.

894Execution. A requestor MUST NOT specify “executionMode=‘asynchronous’” in a 895. A requestor MUST specify “executionMode=‘synchronous’” or (a 896requestor MUST) omit the execution attribute. This is because a requestor SHOULD examine 897each target definition to see whether the target supports the Async Capability before making a 898request that specifies “executionMode=‘asynchronous’” (rather than assuming that the 899provider supports asynchronous execution of requested operations). Since a requestor typically 900must perform the listTargets operation only once at the beginning of a session, this restriction 901should not be too onerous. 902For more information, see the section entitled “Determining execution type”.

3607212bb8d0cf1f11a2b881ca263fc19f.doc Page 32 of 158 903No required content. A requires no sub-element (i.e., to act as an 904argument).

9053.5.1.1.2 Response (normative)

906A provider that receives a from a requestor that it trusts MUST return to 907the requestor a . 908Execution. A provider MUST execute a listTargets operation synchronously. This is because a 909provider must allow the requestor to examine each target definition to see whether the target 910supports the Async Capability (and thus whether the provider might choose to execute a requested 911operation asynchronously) before the provider chooses to execute a requested operation 912asynchronously. Since a requestor typically must perform the listTargets operation only once at the 913beginning of a session, this restriction should not be too onerous.

914If a requestor specifies “executionMode=‘asynchronous’”, a provider MUST fail the operation 915with “error=’unsupportedExecutionMode’”. 916For more information, see the section entitled “Determining execution type”.

917Status. A MUST have a “status” attribute that indicates whether 918the provider successfully processed the request. See “Status (normative)” for values of this 919attribute.

920Error. If the provider cannot return a list of its targets, the MUST 921contain an error attribute that characterizes the failure. See “Error (normative)” for values of this 922attribute.

923Target. A that specifies “status='success'” MUST contain at 924least one element. Each MAY have a “targetID” attribute.

925 If the contains only one 926 then the MAY omit “targetID”.

927 If the contains more than one 928 then each MUST specify “targetID”.

929Any value of “targetID” MUST identify each target uniquely within the namespace of the 930provider.

931Schema. A MUST contain at least one element. Each element 932MUST contain (or MUST refer to) some form of XML Schema that defines the structure of XML 933objects.

934Schema content. Each element MAY include any number of elements.

935 If an element contains no element, 936 then that element MUST have a valid “ref” attribute (see below).

937 If an element contains at least one element, 938 then this takes precedence over the value of any “ref” attribute of that . 939 In this case, the requestor SHOULD ignore the value of any “ref” attribute.

940Each element (that an element contains) MUST include the XML 941namespace of the schema.

942Schema ref. Each MAY have a “ref” attribute. If an element 943has a “ref” attribute, then:

3707212bb8d0cf1f11a2b881ca263fc19f.doc Page 33 of 158 944 The “ref” value MUST be a URI that uniquely identifies the schema. 945 The “ref” value MAY be a location of a schema document 946 (e.g. the physical URL of an XSD file). 947A requestor should ignore any “ref” attribute of an element that contains an 948. (See “Schema content” immediately above.)

949Supported Schema Entities. A target MAY declare as part of its the set of 950schema entities for which the target supports the basic SPML operations (i.e., add, lookup, modify 951and delete). The target MAY contain any number of 952 elements. Each MUST refer to an 953entity in the target schema. (See “SupportedSchemaEntity entityName” and 954“SupportedSchemaEntity targetID” below.) 955A provider that explicitly declares a set of schema entities that a target supports has implicitly 956declared that the target supports only those schema entities. If a target schema contains at least 957one , then the provider MUST support the basic SPML operations 958for (objects on that target that are instances of) any target schema entity to which a 959 refers. 960A provider that does not explicitly declare as part of a target at least one schema entity that the 961target supports has implicitly declared that the target supports every schema entity. If a target 962schema contains no , then the provider MUST support the basic 963SPML operations for (objects on that target that are instances of) any top-level entity in the target 964schema. 965A provider SHOULD explicitly declare the set of schema entities that each target supports. In 966general, the syntactic convenience of omitting the declaration of supported schema entities (and 967thereby implicitly declaring that the provider supports all schema entitities) is not worth the burden 968that this imposes on each requestor. When a provider omits the declaration of supported schema 969entitities, each requestor must determine the set of schema entities that the target supports. This 970process is especially laborious for a requestor that functions without a lot of a priori knowledge.

971SupportedSchemaEntity entityName. Each MUST refer to an 972entity in the schema (of the target that contains the ): 973 In the XSD Profile [SPMLv2-Profile-XSD ], each MUST specify 974 a QName (as the value of its “entityName” attribute). 975 In the DSMLv2 Profile [SPMLv2-Profile-DSML], each MUST 976 specify the name of an objectclass (as the value of its “entityName” attribute).

977SupportedSchemaEntity targetID. A MAY specify a “targetID” 978value: 979 A provider MAY omit “targetID” in any . 980 (That is, a provider MAY omit the optional “targetID” attribute of 981 {SchemaEntityRefType} in a element.) 982 Any “targetID” in a MUST refer to the containing target. 983 (That is, the value of any “targetID” attribute that a specifies 984 MUST match the value of the “targetID” attribute of the element that contains 985 the element.) 986SupportedSchemaEntity isContainer. A MAY have an 987“isContainer” attribute that specifies whether an (object that is an) instance of the supported 988schema entity may contain other objects. 989 If a specifies “isContainer=’true’”, then a provider 990 MUST allow a requestor to add an object beneath any instance of the schema entity.

3807212bb8d0cf1f11a2b881ca263fc19f.doc Page 34 of 158 991 If a specifies “isContainer=’false’” 992 (or if a does not specify “isContainer”), then a provider 993 MUST NOT allow a requestor to add an object beneath any instance of the schema entity. 994Capabilities. A target may also declare a set of capabilities that it supports. Each capability defines 995optional operations or semantics. For general information, see the Capability topic within the 996Concepts section.

997A element MAY contain at most one element. A 998element MAY contain any number of elements. 999Capability. Each declares support for exactly one capability: 1000 Each element MUST specify (as the value of its “namespaceURI” attribute) 1001 an XML namespace that identifies the capability. 1002 Each element MAY specify (as the value of its “location” attribute) the URL 1003 of an XML schema that defines any structure that is associated with the capability 1004 (e.g., an SPML request/response pair that defines an operation—see below).

1005Capability operations. An XML schema document that a capability “location” attribute 1006specifies MAY define operations. An XML schema document for a capability MUST define any 1007operation as a paired request and response such that both of the following are true: 1008 The (XSD type of the) request (directly or indirectly) extends {RequestType} 1009 The (XSD type of the) response (directly or indirectly) extends {ResponseType} 1010Capability appliesTo. A target may support a capability for all of the target’s supported schema 1011entities or only for a specific subset of the target’s supported schema entities. Each capability 1012element may specify any number of supported schema entities to which it applies. A capability that 1013does not specify a supported schema entity to which it applies must apply to every supported 1014schema entity.

1015A element MAY contain any number of elements.

1016A element that contains no element MUST apply to every schema 1017entity that the target supports. If the XML schema for the capability defines an operation, the 1018provider MUST support the capability-defined operation for (any object that is instance of) any 1019schema entity that the target supports. If the capability implies semantic meaning, then the provider 1020SHOULD apply that semantic meaning to (every object that is an instance of) any schema entity 1021that the target supports.

1022Capability appliesTo entityName. Each element MUST have an “entityName” 1023attribute that refers to a supported schema entity of the containing target. (See the discussion of 1024"Supported Schema Entities entityName" earlier in this section.) 1025 In the XSD Profile, each element MUST specify a QName 1026 (as the value of its “entityName” attribute). 1027 In the DSMLv2 Profile [SPMLv2-Profile-DSML], each element MUST specify 1028 the name of an objectclass (as the value of its “entityName” attribute).

1029An element MAY have a “targetID” attribute. 1030 A provider MAY omit “targetID” in any . 1031 (That is, a provider MAY omit the optional “targetID” attribute of 1032 {SchemaEntityRefType} in an element.) 1033 Any “targetID” MUST refer to the containing target. 1034 (That is, any “targetID” attribute of an element

3907212bb8d0cf1f11a2b881ca263fc19f.doc Page 35 of 158 1035 MUST contain the same value as the “targetID” attribute 1036 of the element that contains the element.) 1037Capability content. SPMLv2 specifies only the optional element as content for 1038most capability elements. However, a declaration of support for the reference capability is special.

1039A element that refers to the Reference Capability (i.e., any that 1040specifies “namespaceURI=’urn:oasis:names:tc:SPML:2.0:reference’”) MUST contain 1041(as open content) at least one element. 1042(For normative specifics, please see the “Reference Definition” topic below. 1043For background and for general information, please see the Reference Capability section. 1044For Reference Capability XSD, please see Appendix F.)

1045ReferenceDefinition. Each element MUST be an instance of 1046{spmlref:ReferenceDefinitionType}. Each reference definition names a type of reference, 1047specifies a “from” schema entity and specifies a set of “to” schema entities. Any instance of the 1048“from” schema entity may refer to any instance of any “to” schema entity using the type of reference 1049that the reference definition names.

1050ReferenceDefinition typeOfReference. Each element MUST have a 1051“typeOfReference” attribute that names the type of reference.

1052ReferenceDefinition schemaEntity. Each element MUST contain 1053exactly one sub-element that specifies a “from” schema entity for that type of 1054reference.

1055 The MUST have an “entityName” attribute that refers to a supported 1056 schema entity of the containing target. (See the discussion of “Supported Schema Entities” 1057 earlier in this section.)

1058 The MAY have a “targetID” attribute. Any “targetID” that the 1059 specifies MUST refer to the containing target. 1060 (That is, any“targetID” value that a specifies 1061 MUST match the value of the “targetID” attribute of the element 1062 that contains the .)

1063ReferenceDefinition canReferTo. Each element MAY contain any 1064number of sub-elements, each of which specifies a valid “to” schema entity. A 1065 element that contains no element implicitly declares 1066that any instance of any schema entity on any target is a valid “to” schema entity.

1067 A element MUST have an “entityName” attribute that refers to a supported 1068 schema entity. The value of the “entityName” attribute MUST be the name of a top-level 1069 entity that is valid in the schema.

1070 A element SHOULD have a “targetID” attribute.

1071 - If the contains only one , 1072 then any element MAY omit “targetID”.

1073 - If the contains more than one , 1074 then any element MUST specify “targetID”.

1075 - If the element specifes “targetID”, 1076 then the “entityName” attribute (of the element) 1077 MUST refer to a supported schema entity of the specified target

4007212bb8d0cf1f11a2b881ca263fc19f.doc Page 36 of 158 1078 (i.e., the whose “targetID” value matches 1079 the “targetID” value that the element specifies).

1080 - If the element does not specify “targetID”, 1081 then the “entityName” attribute (of the element) 1082 MUST refer to a supported schema entity of the containing target 1083 (i.e., the that contains the ).

1084ReferenceDefinition referenceDataType. Each element MAY 1085contain any number of sub-elements, each of which specifies a schema 1086entity that is a valid structure for reference data. A element that 1087contains no element implicitly declares that an instance of that type of 1088reference will never contain reference data.

1089 A element MUST have an “entityName” attribute that refers to a 1090 supported schema entity. The value of the “entityName” attribute MUST be the name of a 1091 top-level entity that is valid in the schema.

1092 A element SHOULD have a “targetID” attribute.

1093 - If the contains only one , 1094 then any element MAY omit “targetID”.

1095 - If the contains more than one , 1096 then any element MUST specify “targetID”.

1097 - If the element specifes “targetID”, 1098 then the “entityName” attribute (of the element) 1099 MUST refer to a supported schema entity of the specified target 1100 (i.e., the whose “targetID” value matches 1101 the “targetID” value that the element specifies).

1102 - If the element does not specify “targetID”, 1103 then the “entityName” attribute (of the element) 1104 MUST refer to a supported schema entity of the containing target 1105 (i.e., the that contains the ).

11063.5.1.1.3 Examples (non-normative)

1107In the following example, a requestor asks a provider to list the targets that the provider exposes for 1108provisioning operations. 1109The provider returns a . The “status” attribute of the 1110 element indicates that the listTargets request was successfully 1111processed. The contains two elements. Each 1112describes an endpoint that is available for provisioning operations.

4107212bb8d0cf1f11a2b881ca263fc19f.doc Page 37 of 158

4207212bb8d0cf1f11a2b881ca263fc19f.doc Page 38 of 158 1113This example contains two instances of : target1 and 1114target2. Each of these targets contains a simple schema.

1115The schema for target1 defines two entities: Account and Group. The schema for target1 1116declares both of these entities as supported schema entities. The provider declares that target1 1117supports the Bulk capability and Search capability for both Account and Group. The provider also 1118declares that target1 supports the Password, Suspend, and Reference capabilities for Account.

1119The schema for target2 defines three entities: Person, Organization and 1120OrganizationalUnit. The schema for target2 declares all of these entities as supported 1121schema entities. The provider declares that target2 supports the Bulk capability and Search 1122capability for both schema entities. The provider also declares that target2 supports the 1123Password, Suspend, and Reference capabilities for Person.

1124Reference Definitions. Within target1’s declaration of the Reference Capability for Account, 1125the provider also declares two types of references: owner and memberOf. The provider declares 1126that an instance of Account on target1 may refer to an instance of Person on target2 as its 1127owner. An instance of Account on target1 may also use a memberOf type of reference to refer 1128to an instance of Group on target1.

4307212bb8d0cf1f11a2b881ca263fc19f.doc Page 39 of 158 1129Within target2’s declaration of the Reference Capability for Person, the provider declares that a 1130Person on target2 may own an account on target1. (That is, an instance of Person on target2 1131may use an owns type of reference to refer to an instance of Account on target1.) Note that the 1132“owns” type of reference may be (but is not necessarily) an inverse of the “owner” type of 1133reference. For more information, please see the “Reference Capability” section. 1134NOTE: Subsequent examples within this section will build on this example, using the target 1135definitions returned in this example. Examples will also build upon each other. An object that is 1136created in the example of the add operation will be modified or deleted in later examples.

11373.5.1.2 add

1138The add operation enables a requestor to create a new object on a target and (optionally) to bind 1139the object beneath a specified parent object (thus forming a hierarchy of containment). 1140The subset of the Core XSD that is most relevant to the add operation follows.

4407212bb8d0cf1f11a2b881ca263fc19f.doc Page 40 of 158

11413.5.1.2.1 Request (normative)

1142A requestor MUST send an to a provider in order to (ask the provider to) create a 1143new object. 1144Execution. A requestor MAY specify a type of execution for the add operation. See the section 1145entitled “Determining execution type”.

1146TargetId. An SHOULD specify “targetID”. 1147 If the provider exposes only one target in its , 1148 then a requestor MAY omit the "targetID" attribute of an . 1149 If the provider exposes more than one target in its , 1150 then a requestor MUST specify the "targetID" attribute of an . 1151 Any "targetID" value must specify a valid target. (That is, the value of any "targetID" in 1152 an MUST match the "targetID" of a that is contained in the 1153 provider's .)

1154psoID. An MAY contain a . (A requestor supplies in order to 1155suggest to the provider an identifier for the new object. The provider determines the actual 1156identifier for the new object and returns the actual identifier in the to the 1157requestor. Also see the section entitled “PSO Identifier (normative)”.)

1158ContainerId. An MAY contain a . (A requestor supplies 1159 in order to specify an existing object under which the the new object should be 1160bound.) 1161 A requestor that wants to bind a new object in the top-level namespace of a target 1162 MUST NOT supply . 1163 A requestor that wants to bind a new object beneath a specific object on a target 1164 MUST supply . Any must identify an existing object. 1165 (That is, the content of in an must match the of an 1166 object that already exists on the target.)

4507212bb8d0cf1f11a2b881ca263fc19f.doc Page 41 of 158 1167Data. An MUST contain a element that supplies initial content for the new 1168object. A element MUST contain only elements and attributes defined by the target 1169schema as valid for the schema entity of which the object to be added is an instance.

1170CapabilityData. An element MAY contain any number of 1171elements. Each element contains an item of capability-specific data—for 1172example, a reference to another object. (For more information, see the “Reference Capability” 1173section.)

1174ReturnData. An MAY have a “returnData” attribute that tells the provider 1175which types of data to include in the provider’s response. 1176 A requestor that wants the provider to return nothing of the added object 1177 MUST specify “returnData=’nothing’”. 1178 A requestor that wants the provider to return only the identifier of the added object 1179 MUST specify “returnData=’identifier’”. 1180 A requestor that wants the provider to return the identifier of the added object 1181 plus the XML representation of the object (as defined in the schema of the target) 1182 MUST specify “returnData=’data’”. 1183 A requestor that wants the provider to return the identifier of the added object 1184 plus the XML representation of the object (as defined in the schema of the target) 1185 plus any capability-specific data that is associated with the object 1186 MAY specify “returnData=’everything’” or MAY omit the “returnData” attribute 1187 (since “returnData=’everything’” is the default).

11883.5.1.2.2 Response (normative)

1189A provider that receives an from a requestor that the provider trusts MUST 1190examine the content of the . If the request is valid, the provider MUST create the 1191requested object under the specified parent (i.e., target or container object) if it is possible to do so. 1192Data. The provider MUST create the object with any XML element or attribute contained by the 1193 element in the . 1194CapabilityData. The provider SHOULD associate with the created object the content of each 1195 that the contains. The “mustUnderstand” attribute of 1196each indicates whether the provider MUST associate the content of the 1197 with the created object.

1198 If a element specifies “mustUnderstand=’true’” 1199 then the provider MUST associated the content of the element with the 1200 created object. If the provider cannot associate the content with the 1201 created object then the MUST specify “status=’failure’”.

1202 If a element specifies “mustUnderstand=’false’” 1203 or (if a element) does not specify “mustUnderstand”, 1204 then the provider SHOULD associate the content of the element with the 1205 created object. However, if the provider cannot associate the content 1206 with the created object then) the SHOULD specify “status=’success’”.

1207The SHOULD contain an for each 1208element that the provider could not associate with the created object.

4607212bb8d0cf1f11a2b881ca263fc19f.doc Page 42 of 158 1209Execution. If an does not specify a type of execution, a provider MUST choose a 1210type of execution for the requested operation. See the section entitled “Determining execution 1211type”.

1212Response. The provider must return to the requestor an .

1213Status. The MUST have a “status” attribute that indicates whether the 1214provider successfully created the requested object. See “Status (normative)” for values of this 1215attribute. 1216PSO and ReturnData. If the provider successfully created the requested object, the 1217 MUST contain an element that contains the (XML representation of the) 1218newly created object.

1219 A element MUST contain a element. 1220 The element MUST contain the identifier of the newly created object. 1221 See the section entitled “PSO Identifier (normative)”.

1222 A element MAY contain a element. 1223 - If the specified “returnData=’identifier’” 1224 then the MUST NOT contain a element. 1225 - Otherwise, if the specified “returnData=’data’” 1226 or (if the specified) “returnData=’everything’” 1227 or (if the ) omitted the “returnData” attribute, 1228 then the element MUST contain the XML representation of the object. 1229 This XML must be valid according to the schema of the target for the schema entity of 1230 which the newly created object is an instance.

1231 A element MAY contain any number of elements. Each 1232 element contains an item of capability-specific data that is associated 1233 with the newly created object (for example, a reference to another object). 1234 - If the “returnData=’identifier’” 1235 or (if the specified) “returnData=’data’” 1236 then the MUST NOT contain a element. 1237 - Otherwise, if the specified “returnData=’everything’” 1238 or (if the ) omitted the “returnData” attribute 1239 then the MUST contain a element for each item of 1240 capability-specific data that is associated with the newly created object.

1241Error. If the provider cannot create the requested object, the MUST contain an 1242“error” attribute that characterizes the failure. See “Error (normative)” for values of this attribute. 1243The provider MUST return an error if any of the following is true:

1244 An specifies "targetID", but the value of “targetID” does not identify a 1245 target that the provider supports.

1246 An specifies "targetID" and (the also) contains 1247 , but the value of the "targetID" attribute in the does not 1248 match the value of the "targetID" attribute in the .

1249 An contains , but the content of does not 1250 identify an object that exists. (That is, does not match the of an 1251 object that exists.)

4707212bb8d0cf1f11a2b881ca263fc19f.doc Page 43 of 158 1252 An contains , but the (of 1253 which identifies an instance) does not specify “isContainer=’true’” 1254 In this case, the SHOULD specify “error=’invalidContainment’”.

1255 An contains but the target does not allow the specified 1256 parent object to contain the object to be created. 1257 In this case, the SHOULD specify “error=’invalidContainment’”.

1258 The element is missing an element or attribute that is required (according to the 1259 schema of the target) for the object to be added.

1260 A element specifies “mustUnderstand=’true’” and the provider 1261 cannot associate the content of the with the object to be created. 1262The provider MAY return an error if:

1263 The element contains data that the provider does not recognize as valid according to 1264 the target schema for the type of object to be created.

1265 The provider does not recognize the content of a element as specific to 1266 any capability that the target supports (for the schema entity of which the object to be created is 1267 an instance).

12683.5.1.2.3 Examples (non-normative)

1269In the following example, a requestor asks a provider to add a new person. The requestor specifies 1270the attributes required for the Person schema entity (cn, firstName, lastName and fullName). 1271The requestor also supplies an optional email address for the person. This example assumes that 1272a container named “ou=Development, org=Example” already exists. [email protected] 1273The provider returns an element. The “status” attribute of the 1274 element indicates that the add request was successfully processed. The 1275 contains an element that identifies the newly created object. 1276This requestor will need this value for any subsequent operation on the newly created object. [email protected]

4807212bb8d0cf1f11a2b881ca263fc19f.doc Page 44 of 158 1277Next, the requestor asks a provider to add a new account. The requestor specifies a name for the 1278account. The requestor also specifies references to a Group that resides on target1 and to a 1279Person (from the first example in this section) that resides on target2. 1280The provider returns an element. The “status” attribute of the 1281 element indicates that the add operation was successfully processed. The 1282 contains an element that identifies the newly created object. 1283This requestor will need this value for any subsequent operation on the newly created object.

12843.5.1.3 lookup

1285The lookup operation enables a requestor to obtain the XML that represents an object on a target. 1286The lookup operation also obtains any capability-specific data that is associated with the object. 1287The subset of the Core XSD that is most relevant to the lookup operation follows.

4907212bb8d0cf1f11a2b881ca263fc19f.doc Page 45 of 158

12883.5.1.3.1 Request (normative)

1289A requestor MUST send a to a provider in order to (ask the provider to) return 1290(the XML that represents) an existing object.

5007212bb8d0cf1f11a2b881ca263fc19f.doc Page 46 of 158 1291Execution. A requestor MAY specify a type of execution for a lookup operation. See Determining 1292execution type.

1293In general, a provider SHOULD NOT specify “executionMode=‘asynchronous’”. The reason 1294for this is that the status of a lookup should reflect the current state of a target object. If a lookup 1295operation is executed asynchronously then other operations are more likely to intervene.

1296PsoId. A MUST contain at least one that specifies an object to be 1297returned. The content of each MUST identify an existing object on a target.

1298ReturnData. A MAY have a “returnData” attribute that tells the provider 1299which subset of (the XML representation of) each to include in the provider’s response. 1300 A requestor that wants the provider to return nothing of each requested object 1301 MUST specify “returnData=’nothing’”. 1302 A requestor that wants the provider to return only the identifier of each requested object 1303 MUST specify “returnData=’identifier’”. 1304 A requestor that wants the provider to return the identifier of each requested object 1305 plus the XML representation of the object (as defined in the schema of the target) 1306 MUST specify “returnData=’data’”. 1307 A requestor that wants the provider to return the identifier of each requested object 1308 plus the XML representation of the object (as defined in the schema of the target) 1309 plus any capability-specific data that is associated with the object 1310 MAY specify “returnData=’everything’” or MAY omit the “returnData” attribute 1311 (since “returnData=’everything’” is the default).

13123.5.1.3.2 Response (normative)

1313A provider that receives a from a requestor that the provider trusts MUST 1314examine the content of the . If the request is valid, the provider MUST return 1315(the XML that represents) each requested object if it is possible to do so.

1316Execution. If an does not specify “execution”, the provider MUST choose 1317a type of execution for the requested operation. See the section entitled “Determining execution 1318type”. 1319A provider SHOULD execute a lookup operation synchronously if it is possible to do so. The reason 1320for this is that the status of a lookup should reflect the current state of a target object. If a lookup 1321operation is executed asynchronously then other operations are more likely to intervene.

1322Response. The provider must return to the requestor a .

1323Status. The must have a “status” that indicates whether the provider 1324successfully returned each requested object. See ‘Status (normative)’ for values of this attribute. 1325PSO and ReturnData. If the provider successfully returned each requested object, the 1326 MUST contain an element for each requested object. Each 1327contains the subset of (the XML representation of) a requested object that the “returnData” 1328attribute of the specified. By default, each contains the entire (XML 1329representation of an) object.

1330 A element MUST contain a element. 1331 The element MUST contain the identifier of the requested object. 1332 See the section entitled “PSO Identifier (normative)”.

1333 A element MAY contain a element.

5107212bb8d0cf1f11a2b881ca263fc19f.doc Page 47 of 158 1334 - If the specified “returnData=’identifier’”, 1335 then the MUST NOT contain a element. 1336 - Otherwise, if the specified “returnData=’data’” 1337 or (if the specified) “returnData=’everything’” 1338 or (if the ) omitted the “returnData” attribute 1339 then the element MUST contain the XML representation of the object. 1340 This XML must be valid according to the schema of the target for the schema entity of 1341 which the newly created object is an instance.

1342 A element MAY contain any number of elements. Each 1343 element contains an item of capability-specific data that is associated 1344 with the newly created object (for example, a reference to another object). 1345 - If the specified “returnData=’identifier’” 1346 or (if the specified) “returnData=’data’” 1347 then the MUST NOT contain a element. 1348 - Otherwise, if the specified “returnData=’everything’” 1349 or (if the ) omitted the “returnData” attribute, 1350 then the MUST contain a element for each item of capability- 1351 specific data that is associated with the requested object 1352 (and that is specific to a capability that the target supports for the schema entity of which 1353 the requested object is an instance).

1354Error. If the provider cannot return the requested object, the must have an 1355“error” attribute that characterizes the failure. See “Error (normative)” for values of this attribute. 1356The provider MUST return an error if any of the following is true:

1357 A contains no .

1358 A contains a that does not identify an object that exists on a 1359 target. 1360The provider MAY return an error if:

1361 A contains data that the provider does not recognize.

13623.5.1.3.3 Examples (non-normative)

1363In the following example, a requestor asks a provider to return the person object from the add 1364examples above. The requestor specifies the identifier for the person object. 1365The provider returns a element. The “status” attribute of the 1366 element indicates that the lookup request was successfully processed. The 1367 contains a element that contains the requested object.

1368The element contains a element that contains the PSO Identifier.

5207212bb8d0cf1f11a2b881ca263fc19f.doc Page 48 of 158 Briggs”> [email protected] 1369Next, the requestor asks a provider to return the account object from the add examples above. The 1370requestor specifies a for the account object. 1371The provider returns a element. The “status” attribute of the 1372 element indicates that the add request was successfully processed. The 1373 contains a element that contains the requested object.

1374The element contains a element which content uniquely identifies the object. In 1375this example, the element also contains two reference elements. The lookup operation 1376automatically includes capability-specific data (such as these two reference elements) if the 1377schema for the target declares that it supports the reference capability (for the schema entity of 1378which the requested object is an instance). 1379To illustrate the effect of the “returnData” attribute, let’s reissue the previous request and 1380specify a value of “returnData” other than the default (which is 1381“returnData=’everything’”). First, assume that the requestor specifies 1382“returnData=’identifier’”. 1383The response specifies “status=’success’” which indicates that the lookup operation 1384succeeded and that the requested object exists. Since the request specifies 1385“return=’identifier’”, the in the response contains the but no .

5307212bb8d0cf1f11a2b881ca263fc19f.doc Page 49 of 158 1386Next assume that the requestor specifies “returnData=’data’”. 1387Since the request specifies “return=’data’”, the in the response contains the 1388and but no element. Specifying “return=’data’” returns the 1389XML representation of the object as defined in the schema for the target but suppresses capability- 1390specific data.

1391Specifying “return=’data’” is advantageous if the requestor is not interested in capability- 1392specific data. Omitting capability-specific data may reduce the amount of work that the provider 1393must do in order to build the . Reducing the size of the response should also 1394reduce the network traffic that is required in order to transmit the response. Omitting capability- 1395specific data may also reduce the amount of XML parsing work that the requestor must perform in 1396order to process the response.

13973.5.1.4 modify

1398The modify operation enables a requestor to change an object on a target. The modify operation 1399can change the schema-defined component of an object, any capability-specific data that is 1400associated with the object, or both. 1401Modify can change PSO Identifier. One important subtlety is that a modify operation may change 1402the identifier of the modified object. For example, assume that a provider exposes the 1403Distinguished Name (DN) as the identifier of each object on a target that represents a directory 1404service. In this case, modifying the object’s Common Name (CN) or moving the object beneath a 1405different Organizational Unit (OU) would change the object’s DN and therefore its PSO-ID. 1406In general, the PSTC recommends that each provider expose an immutable identifier as the PSO- 1407ID of each object. In the case of a target that represents a directory service, an immutable identifier 1408could be a Globally Unique IDentifier (GUID) that is managed by the directory service or it could be 1409any form of unique identifier that is managed by the provider. 1410The subset of the Core XSD that is most relevant to the modify operation follows.

5407212bb8d0cf1f11a2b881ca263fc19f.doc Page 50 of 158

5507212bb8d0cf1f11a2b881ca263fc19f.doc Page 51 of 158

14113.5.1.4.1 Request (normative)

1412A requestor MUST send a to a provider in order to (ask the provider to) modify 1413an existing object. 1414Execution. A requestor MAY specify a type of execution for a modify operation. See Determining 1415execution type.

1416PsoId. A MUST contain exactly one . A MUST identify an 1417object that exists on a target that is exposed by the provider.

5607212bb8d0cf1f11a2b881ca263fc19f.doc Page 52 of 158 1418ReturnData. A MAY have a “returnData” attribute that tells the provider 1419which subset of (the XML representation of) each modified to include in the provider’s 1420response. 1421 A requestor that wants the provider to return nothing of the modified object 1422 MUST specify “returnData=’nothing’”. 1423 A requestor that wants the provider to return only the identifier of the modified object 1424 MUST specify “returnData=’identifier’”. 1425 A requestor that wants the provider to return the identifier of the modified object 1426 plus the XML representation of the object (as defined in the schema of the target) 1427 MUST specify “returnData=’data’”. 1428 A requestor that wants the provider to return the identifier of the modified object 1429 plus the XML representation of the object (as defined in the schema of the target) 1430 plus any capability-specific data that is associated with the object 1431 MAY specify “returnData=’everything’” or MAY omit the “returnData” attribute 1432 (since “returnData=’everything’” is the default).

1433Modification. A MUST contain at least one . A 1434 describes a set of changes to be applied (to the object that the 1435specifies). A MUST have a “modificationMode” that specifies the type of 1436change as one of ‘add’, ‘modify’ or ‘delete’. 1437A requestor MAY specify a change to a schema-defined element or attribute of the object to be 1438modified. A requestor MAY specify any number of changes to capability-specific data associated 1439with the object to be modified.

1440A requestor MUST use a element to specify a schema-defined element or attribute 1441of the object to be modified. A requestor MUST use a element to describe 1442each change to a capability-specific data element that is associated with the object to be modified.

1443A element MUST contain a element or (the 1444MUST contain) at least one element. A element MAY 1445contain both a element and one or more elements.

1446Modification component. The sub-element of a specifies a 1447schema-defined element or attribute of the object that is to be modified. This is an instance of 1448{SelectionType}, which occurs in several contexts within SPMLv2. See the section entitled 1449“SelectionType in a Request (normative)”.

1450Modification data. A requestor MUST specify as the content of the sub-element of a 1451 any value that is to be added to, replaced within, or deleted from the element or 1452attribute that the (sub-element of the ) specifies.

1453Modification capabilityData. A requestor MAY specify any number of 1454elements within a element. Each element specifies 1455capability-specific data (for example, a reference to another object) for the object to be modified. 1456Because it is an {ExtensibleType}, a element may validly contain any 1457XML element or attribute. The element SHOULD contain elements that the 1458provider will recognize as specific to a capability that the target supports for the schema entity of 1459which the object to be modified is an instance.

14603.5.1.4.2 Response (normative)

1461A provider that receives a from a requestor that the provider trusts MUST 1462examine the content of the . If the request is valid, the provider MUST apply

5707212bb8d0cf1f11a2b881ca263fc19f.doc Page 53 of 158 1463each requested (to the object that is specified by the 1464corresponding to that ) if it is possible to do so.

1465Execution. If an does not have an execution attribute, the provider MUST 1466choose a type of execution for the requested operation. See the section entitled “Determining 1467execution type”.

1468Response. The provider must return to the requestor a .

1469Status. The must have a “status” attribute that indicates whether the 1470provider successfully applied the requested modifications to each identified object. See “Status 1471(normative)” for values of this attribute. 1472PSO and ReturnData. If the provider successfully modified the requested object, the 1473 MUST contain an element. The contains the subset of (the 1474XML representation of) a requested object that the “returnData” attribute of the 1475 specified. By default, the contains the entire (XML representation of 1476the) modified object.

1477 A element MUST contain a element. 1478 The element MUST contain the identifier of the requested object. 1479 See the section entitled “PSO Identifier (normative)”.

1480 A element MAY contain a element. 1481 - If the specified “returnData=’identifier’”, 1482 then the MUST NOT contain a element. 1483 - Otherwise, if the specified “returnData=’data’” 1484 or (if the specified) “returnData=’everything’” 1485 or (if the ) omitted the “returnData” attribute 1486 then the element MUST contain the XML representation of the object. 1487 This XML must be valid according to the schema of the target for the schema entity of 1488 which the newly created object is an instance.

1489 A element MAY contain any number of elements. Each 1490 element contains an item of capability-specific data that is associated 1491 with the newly created object (for example, a reference to another object). 1492 - If the specified “returnData=’identifier’” 1493 or (if the specified) “returnData=’data’” 1494 then the MUST NOT contain a element. 1495 - Otherwise, if the specified “returnData=’everything’” 1496 or (if the ) omitted the “returnData” attribute, 1497 then the MUST contain a element for each 1498 item of capability-specific data that is associated with the requested object 1499 (and that is specific to a capability that the target supports for the schema entity of which 1500 the requested object is an instance).

1501Error. If the provider cannot modify the requested object, the must have an 1502“error” attribute that characterizes the failure. See “Error (normative)” for values of this attribute. 1503The provider MUST return an error if any of the following is true:

1504 The contains a for which there is no corresponding 1505 .

1506 A contains neither a nor a .

5807212bb8d0cf1f11a2b881ca263fc19f.doc Page 54 of 158 1507 A is empty (that is, a component element has no content).

1508 A specifies an element or attribute that is not valid (according to the schema of 1509 the target) for the type of object to be modified. 1510The provider MAY return an error if:

1511 A contains data that the provider does not recognize as specifying an XML 1512 element or attribute that is valid according to the target schema for the type of object to be 1513 modified.

1514 A contains data that the provider does not recognize as capability- 1515 specific data (i.e., one or more XML elements that correspond to a capability that the target 1516 supports for the type of object to be modified). 1517In addition, see the section entitled “SelectionType Errors (normative)”.

15183.5.1.4.3 Examples (non-normative)

1519In the following example, a requestor asks a provider to modify the email address for an existing 1520Person object. [email protected] 1525In the following example, a requestor asks a provider to modify the same Person object, adding a 1526reference to an Account that the Person owns. (Since the request is to add capability-specific data, 1527the element contains no sub-element.)

5907212bb8d0cf1f11a2b881ca263fc19f.doc Page 55 of 158 1528The provider returns a element. The “status” attribute of the 1529 element indicates that the modify request was successfully processed. The 1530 element of the shows that the provider has added (the 1531 that is specific to) the “owns” reference. [email protected] 1532 1533Modifying a reference. Since SPMLv2 does not specify any mechanism to define the cardinality of 1534a type of reference, a requestor should not assume that a provider enforces any specific cardinality 1535for any type of reference. For a general discussion of the issues surrounding references, see the 1536section entitled “Reference Capability”. 1537In our next example, the requestor wishes to change the owner of an Account from “2244” (which is 1538the PSO-ID of “Person:joebob”) to “2245” (which is the PSO-ID of “Person:billybob”). Assume that 1539each account should have at most one owner. If the requestor could trust the provider to enforce 1540this, and if the requestor could trust that no other requestor has changed the value of “owner”, the 1541requestor could simply ask the provider to replace the owner value 2244 with 2245. However, 1542since our requestor is both cautious and general, the requestor instead nests two 1543 elements within a single : 1544- one to delete any current values of “owner” and 1545- one to add the desired value of “owner”.

6007212bb8d0cf1f11a2b881ca263fc19f.doc Page 56 of 158 1546The provider returns a element. The “status” attribute of the 1547 element indicates that the modify request was successfully processed. The 1548 element of the shows that the (capability data that is specific to the) 1549“owner” reference has been deleted.

15503.5.1.5 delete

1551The delete operation enables a requestor to remove an object from a target. The delete operation 1552automatically removes any capability-specific data that is associated with the object. 1553The subset of the Core XSD that is most relevant to the delete operation follows.

6107212bb8d0cf1f11a2b881ca263fc19f.doc Page 57 of 158 15543.5.1.5.1 Request (normative)

1555A requestor MUST send a to a provider in order to (ask the provider to) 1556remove an existing object. 1557Execution. A requestor MAY specify a type of execution for a delete operation. See Determining 1558execution type.

1559PsoId. A MUST contain a element that identifies the object to 1560delete.

1561Recursive. A MAY have a “recursive” attribute that specifies whether the 1562provider should delete (along with the specified object) any object that the specified object (either 1563directly or indirectly) contains. 1564 A requestor that wants the provider to delete any object that the specified object contains 1565 (along with the specified object) MUST specify “recursive=’true’”. 1566 A requestor that wants the provider to delete the specified object only if the specified object 1567 contains no other object MUST NOT specify “recursive=’true’”. Such a requestor MAY 1568 specify “recursive=’false’” or (such a requestor MAY) omit the “recursive” attribute 1569 (since ‘false’ is the default value).

1570CapabilityData. A MAY contain any number of 1571elements. Because {DeleteRequestType} extends {RequestType} and because other request 1572types (such as and ) must be able to contain capability- 1573specific data, it is syntactically valid for a to contain capability-specific data.

1574A SHOULD NOT contain a element. The reason for this 1575is that capability-specific data are meaningless to a delete operation.

15763.5.1.5.2 Response (normative)

1577A provider that receives a from a requestor that the provider trusts MUST 1578examine the content of the request. If the request is valid, the provider MUST delete the object 1579(that is specified by the sub-element of the ) if it is possible to do so.

1580Execution. If an does not have an “execution” attribute, the provider 1581MUST choose a type of execution for the requested operation. See the section entitled 1582“Determining execution type”.

1583CapabilityData. A provider MUST ignore any sub-element that a 1584 contains. (Since capability-specific data are irrelevant to a delete operation, 1585there is nothing to be gained by returning an error.) 1586Recursive. A provider MUST NOT delete an object that contains another object unless the 1587 specifies “recursive=’true’”. If the specifies 1588“recursive=’true’” then the provider must delete the specified object along with any object 1589that the specified object (directly or indirectly) contains.

1590Response. The provider must return to the requestor a .

1591Status. A must contain a “status” attribute that indicates whether the 1592provider successfully deleted the specified object. See “Status (normative)” for values of this 1593attribute.

6207212bb8d0cf1f11a2b881ca263fc19f.doc Page 58 of 158 1594Error. If the provider cannot delete the specified object, the must contain an 1595“error” attribute that characterizes the failure. See “Error (normative)” for values of this attribute. 1596The provider MUST return an error if any of the following is true:

1597 The sub-element of the is empty (that is, the identifier 1598 element has no content). In this case, the SHOULD specify 1599 “error=’noSuchIdentifier’”.

1600 The sub-element of the contains invalid data. In this case the 1601 provider SHOULD return “error=’unsupportedIdentifierType’”.

1602 The sub-element of the does not specify an object that exists. In 1603 this case the MUST specify “error=’noSuchIdentifier’”.

1604 The sub-element of the specifies an object that contains another 1605 object and the does not specify “recursive=’true’”. In such a case 1606 the provider should return “error=’containerNotEmpty’”.

16073.5.1.5.3 Examples (non-normative)

1608In the following example, a requestor asks a provider to delete an existing Person object. 1609The provider returns a element. The “status” attribute of the 1610 element indicates that the delete request was successfully processed. The 1611 contains no other data. 1612

6307212bb8d0cf1f11a2b881ca263fc19f.doc Page 59 of 158 1613

16143.5.2 Async Capability

1615The Async Capability is defined in a schema associated with the following XML namespace: 1616urn:oasis:names:tc:SPML:2:0:async. The Async Capability XSD is included as Appendix B 1617to this document.

1618A provider that supports asynchronous execution of requested operations for a target SHOULD 1619declare that the target supports the Async Capability. A provider that does not support 1620asynchronous execution of requested operations MUST NOT declare that the target supports the 1621Async Capability. 1622IMPORTANT: The Async Capability does NOT define an operation specific to requesting 1623asynchronous execution. A provider that supports the Async Capability (for a schema entity of 1624which each object that the requestor desires to manipulate is an instance):

16251) MUST allow a requestor to specify “executionMode=‘asynchronous’”. 1626 The provider MUST NOT fail such a request with 1627 “error=’unsupportedExecutionMode’”. 1628 The provider MUST execute the requested operation asynchronously 1629 (if the provider executes the requested operation at all). 1630 See the section entitled “Requestor specifies asynchronous execution (normative)”. 16312) MAY choose to execute a requested operation aynchronously 1632 when the request does not specify the execution attribute. 1633 See the section entitled “Provider chooses asynchronous execution (normative)”. 1634The Async Capability also defines two operations that a requestor may use to manage another 1635operation that a provider is executing asynchronously: 1636 A status operation allows a requestor to check the status (and possibly results) of an operation. 1637 A cancel operation asks the provider to stop executing an operation. 1638Status. When a provider is executing SPML operations asynchronously, the requestor needs a way 1639to check the status of requests. The status operation allows a requestor to determine whether an 1640asynchronous operation has succeeded, has failed or is still pending. The status operation also 1641allows a requestor to obtain the output of an asynchronous operation. 1642Cancel. A requestor may also need to cancel an asynchronous operation. The cancel operation 1643allows a requestor to ask a provider to stop executing an ansynchronous operation. 1644IMPORTANT: Both the status and cancel operations must be executed synchronously. Because 1645both cancel and status operate on other operations that a provider is executing asynchronously, it 1646would be confusing to execute cancel or status asynchronously. For example, what would it mean 1647to get the status of a status operation? Describing the expected behavior (or interpreting the result) 1648of canceling a cancel operation would be difficult, and the chain could become quite long.

16493.5.2.1 cancel

1650The cancel operation enables a requestor to stop the execution of an asynchronous operation. (The 1651cancel operation itself must be synchronous.) 1652The subset of the Async Capability XSD that is most relevant to the cancel operation follows.

6407212bb8d0cf1f11a2b881ca263fc19f.doc Page 60 of 158

1653Cancel must be synchronous. Because ‘cancel’ operates on another operation that a provider is 1654executing asynchronously, the ‘cancel’ operation itself must be synchronous. (To do otherwise 1655permits unnecessary confusion. What should happen when one cancels a ‘cancel’ operation?) 1656Cancel is not batchable. Because the cancel operation must be synchronous, a requestor must 1657not nest a ‘cancel’ request in a batch request.

1658 Request (normative)

1659A requestor MUST send a to a provider in order to (ask the provider to) cancel 1660a requested operation that the provider is executing asynchronously.

1661Execution. A MUST NOT specify “executionMode=‘asynchronous’”. A 1662requestor MUST specify “executionMode=‘synchronous’” or (a requestor MUST) omit the 1663execution attribute of the . See Determining execution type.

1664AsyncRequestID. A MUST have an “asyncRequestID” attribute that 1665specifies the operation to cancel.

16663.5.2.1.1 Response (normative)

1667A provider that receives a from a requestor that the provider trusts MUST 1668examine the content of the request. If the request is valid, the provider MUST cancel the operation 1669(that the “asyncRequestID” attribute of the specifies) if it is possible for the 1670provider to do so. 1671Execution. The provider MUST execute the cancel operation synchronously (if the provider 1672executes the cancel operation at all). See the section entitled “Determining execution type”.

1673Response. The provider must return to the requestor a .

1674Status. A must have a “status” attribute that indicates whether the 1675provider successfully processed the request to cancel the specified operation. See “Status 1676(normative)” for values of this attribute.

6507212bb8d0cf1f11a2b881ca263fc19f.doc Page 61 of 158 1677Since the provider must execute a cancel operation synchronously, the 1678MUST NOT specify “status=’pending’”. The MUST specify 1679“status=’success’” or (the MUST specify) “status=’failure’”.

1680If the provider successfully canceled the specified operation, the MUST 1681specify “status=’success’”. If the provider failed to cancel the specified operation, the 1682 MUST specify “status=’failure’”.

1683Error. If the provider cannot cancel the specified operation, the MUST 1684contain an “error” attribute that characterizes the failure. See “Error (normative)” for values of 1685this attribute. 1686The provider MUST return an error if any of the following is true:

1687o The “asyncRequestID” attribute of the has no value. In this case, the 1688 SHOULD specify “error=’malformedRequest’”.

1689o The “asyncRequestID” attribute of the does not specify an operation 1690 that exists. In this case the provider SHOULD return “error=’noSuchRequest’”.

16913.5.2.1.2 Examples (non-normative)

1692In order to illustrate the cancel operation, we must first execute an operation asynchronously. In the 1693following example, a requestor first asks a provider to delete a Person asynchronously. 1694The provider returns a element. The “status” attribute of the 1695 element indicates that the provider will execute the delete operation 1696asynchronously. The also returns an “asyncRequestID”. 1697Next, the same requestor asks the provider to cancel the delete operation. 1698The provider returns a . The “status” attribute of the 1699indicates that the provider successfully canceled the delete operation.

17003.5.2.2 status

1701The status operation enables a requestor to determine whether an asynchronous operation has 1702completed successfully, has failed, or is still executing. The status operation also (optionally) 1703enables a requestor to obtain results of an asynchronous operation. (The status operation itself 1704must be synchronous.) 1705The subset of the Async Capability XSD that is most relevant to the status operation is shown 1706below for the convenience of the reader.

6607212bb8d0cf1f11a2b881ca263fc19f.doc Page 62 of 158 use="optional" default="false"/>

1707Status must be synchronous. The ‘status’ operation acts on other operations that a provider is 1708executing asynchronously. The ‘status’ operation itself therefore must be synchronous. (To do 1709otherwise permits unnecessary confusion. What should be the status of a ‘status’ operation?) 1710Status is not batchable. Because the status operation must be synchronous, a requestor must not 1711nest a ‘status’ request in a batch request.

17123.5.2.2.1 Request (normative)

1713A requestor MUST send a to a provider in order to obtain the status or results 1714of a requested operation that the provider is executing asynchronously.

1715Execution. A MUST NOT specify “executionMode=‘asynchronous’”. A 1716requestor MUST specify “executionMode=‘synchronous’” or (a requestor MUST) omit the 1717“executionMode” attribute of the . See Determining execution type.

1718AsyncRequestID. A MAY have an “asyncRequestID” attribute that 1719specifies one operation for which to return status or results. A that omits 1720“asyncRequestID” implicitly requests the status of all operations that the provider has executed 1721asynchronously on behalf of the requestor (and for which operations the provider still retains status 1722and results).

1723returnResults. A MAY have a “returnResults” attribute that specifies 1724whether the requestor wants the provider to return any results (or output) of the operation that is 1725executing asynchronously. If a does not specify “returnResults”, the 1726requestor has implicitly asked that the provider return only the “status” of the operation that is 1727executing asynchronously.

17283.5.2.2.2 Response (normative)

1729A provider that receives a from a requestor that the provider trusts MUST 1730examine the content of the request. If the request is valid, the provider MUST cancel the operation 1731(that the “asyncRequestID” attribute of the specifies) if it is possible for the 1732provider to do so. 1733Execution. The provider MUST execute the status operation synchronously (if the provider 1734executes the status operation at all). See the section entitled “Determining execution type”.

6707212bb8d0cf1f11a2b881ca263fc19f.doc Page 63 of 158 1735ReturnResults. A MAY have a “returnResults” attribute that indicates 1736whether the requestor wants the provider to return in each nested response (in addition to status, 1737which is always returned) any results of (i.e., output or XML content of the response element for) 1738the operation that is executing asynchronously.

1739 If a specifies “returnResults=’true’”, then the provider must also 1740 return in the any results (or output) of each operation.

1741 If a specifies “returnResults=’false’”, then the provider must return 1742 in the only the “status” of the each operation.

1743 If the does not specify a value for “returnResults”, the provider MUST 1744 assume that the requestor wants only the “status” (and not any result) of the operation that 1745 is executing asynchronously.

1746Response. The provider must return to the requestor a .

1747Status. A must have a “status” attribute that indicates whether the 1748provider successfully obtained the status of the specified operation (and obtained any results of the 1749specified operation if the specifies “returnResults=’true’”). See “Status 1750(normative)” for values of this attribute.

1751Since the provider must execute a status operation synchronously, the MUST 1752NOT specify “status=’pending’”. The MUST specify 1753“status=’success’” or (the MUST specify) “status=’failure’”. 1754 If the provider successfully obtained the status of the specified operation (and successfully 1755 obtained any output of the specified operation if the specifies 1756 “returnOutput=’true’”), the MUST specify “status=’success’”. 1757 If the provider failed to obtain the status of the specified operation (or failed to obtain any output 1758 of the specified operation if the specifies “returnOutput=’true’”), the 1759 MUST specify “status=’failure’”.

1760Nested Responses. A MAY contain any number of responses. Each 1761response is an instance of a type that extends {ResponseType}. Each response represents an 1762operation that the provider is executing asynchronously.

1763 A that specifies “status=’failure’” MUST NOT contain an 1764 embedded response. Since the status operation failed, the response should not contain data.

1765 A that specifies “status=’success’” MAY contain any number of 1766 responses.

1767 - If the specifies “asyncRequestID”, 1768 then a successful MUST contain exactly one nested response 1769 that represents the operation that “asyncRequestID” specifies.

1770 - If the omits “asyncRequestID”, 1771 then a successful MUST contain a nested response for each 1772 operation that the provider has executed asynchronously as the result of a request from 1773 that requestor (and for which operation the provider still retains status and results).

1774Nested Response RequestID. Each nested response MUST have a “requestID” attribute that 1775identifies the corresponding operation (within the namespace of the provider).

1776Nested Response Status. Each nested response MUST have a “status” attribute that 1777specifies the current state of the corresponding operation.

6807212bb8d0cf1f11a2b881ca263fc19f.doc Page 64 of 158 1778 A nested response that represents an operation that failed 1779 MUST specify “status=’failure’”. 1780 A nested response that represents an operation that succeeded 1781 MUST specify “status=’success’”. 1782 A nested response that represents an operation that the provider is still executing 1783 MUST specify “status=’pending’”.

1784Nested Response and ReturnResults. If a specifies 1785“returnResults=’true’”, then each response that is nested in the 1786MUST contain any output thus far produced by the corresponding operation.

1787 A nested response that specifies “status=’success’” MUST contain all the output that 1788 would have been contained in a synchronous response for the operation if the provider had 1789 executed the specified operation synchronously.

1790 A nested response that specifies “status=’pending’” MUST contain a subset of the output 1791 that would have been contained in a synchronous response for the operation if the provider had 1792 executed the specified operation synchronously.

1793Error. If the provider cannot obtain the status of the specified operation, the 1794MUST contain an “error” attribute that characterizes the failure. See “Error (normative)” for 1795values of this attribute. 1796The provider MUST return an error if any of the following is true:

1797 The “asyncRequestID” attribute of the has no value. In this case, the 1798 SHOULD specify “error=’malformedRequest’”.

1799 The “asyncRequestID” attribute of the does not specify an operation 1800 that exists. In this case the provider SHOULD return “error=’noSuchRequest’”.

18013.5.2.2.3 Examples (non-normative)

1802In order to illustrate the status operation, we must first execute an operation asynchronously. In this 1803example, a requestor first asks a provider to add a Person asynchronously. [email protected] 1804The provider returns an . The “status” attribute of the 1805indicates that provider will execute the delete operation asynchronously. The also 1806has a “requestID” attribute (even though the original did not specify 1807“requestID”).

1808If the original had specified a “requestID”, then the would 1809specify the same “requestID” value. 1810The same requestor then asks the provider to obtain the status of the add operation. The requestor 1811does not ask the provider to include any output of the add operation.

6907212bb8d0cf1f11a2b881ca263fc19f.doc Page 65 of 158 1812The provider returns a . The “status” attribute of the 1813indicates that the provider successfully obtained the status of the add operation.

1814The also contains a nested that represents the add 1815operation. The specifies “status=’pending’”, which indicates that the add 1816operation has not completed executing. 1817Next, the same requestor asks the provider to obtain the status of the add operation. This time the 1818requestor asks the provider to include any results of the add operation. 1819The provider again returns a . The “status” attribute of the 1820 again indicates that the provider successfully obtained the status of the add 1821operation.

1822The again contains a nested that represents the add 1823operation. The specifies “status=’pending’”, which indicates that the add 1824operation still has not completed executing.

1825Because the statusRequest specified “returnOutput=’true’”, the contains a 1826subset of the output that the add operation will eventually produce if the add operation successfully 1827completes. The element already contains the data that was supplied in the 1828 but the element does not yet contain the element that will be 1829generated when the add operation is complete. [email protected] 1830Finally, the same requestor asks the provider to obtain the status of the add operation. The 1831requestor again asks the provider to include any output of the add operation. 1832The provider again returns a . The “status” attribute of the 1833 again indicates that the provider successfully obtained the status of the add 1834operation.

1835The again contains a nested that represents the add 1836operation. The specifies “status=’success’”, which indicates that the add 1837operation completed successfully.

1838Because the statusRequest specified “returnResults=’true’” and because the 1839 specifies “status=’success’”, the now contains all of the 1840output of the add operation. The element contains the data that was supplied in

7007212bb8d0cf1f11a2b881ca263fc19f.doc Page 66 of 158 1841the and the element also contains the element that was missing 1842earlier. [email protected] 1843

18443.5.3 Batch Capability

1845The Batch Capability is defined in a schema associated with the following XML namespace: 1846urn:oasis:names:tc:SPML:2:0:batch. The Batch Capability XSD is included as Appendix C 1847to this document. 1848A provider that supports batch execution of requested operations for a target SHOULD declare that 1849the target supports the Batch Capability. A provider that does not support batch execution of 1850requested operations MUST NOT declare that the target supports the Batch Capability. 1851The Batch Capability defines one operation: batch.

18523.5.3.1 batch

1853The subset of the Batch Capability XSD that is most relevant to the batch operation follows.

Elements that extend spml:RequestType

7107212bb8d0cf1f11a2b881ca263fc19f.doc Page 67 of 158

Elements that extend spml:ResponseType

1854The batch operation combines any number of individual requests into a single request. 1855No transactional semantics. Using a batch operation to combine individual requests does not 1856imply atomicity (i.e., “all-or-nothing” semantics) for the group of batched requests. A requestor must 1857not assume that the failure of a nested request will undo a nested request that has already 1858completed. (See the section entitled “Transactional Semantics”.) 1859Note that this does not preclude a batch operation having transactional semantics—this is 1860unspecified. A provider (or some higher-level service) with the ability to undo specific operations 1861could support rolling back an entire batch if an operation nested within the batch fails.

1862Nested Requests. The Core XSD defines {RequestType} as the base type for any SPML 1863request. A requestor may group into a any number of requests that derive from 1864{RequestType}. However, there are some exceptions. See the “Batch is not batchable” and 1865“Some operations are not batchable” topics immediately below. 1866Batch is not batchable. A requestor must not nest a ‘batch’ request within another batch request. 1867(To support nested batches would impose on each provider a burden of complexity that the benefits 1868of nested batches do not justify.) 1869Some operations are not batchable. For various reasons, a requestor must not nest certain 1870types of requests within a batch request. For example, a request to listTargets must not be batched 1871(because a requestor cannot know until the requestor examines the response from ‘listTargets’ 1872whether the provider supports the batch capability). Requests to search for objects (and requests 1873to iterate the results of a search) must not be batched for reasons of scale. Batching requests to 1874cancel and obtain the status of asynchronous operations would introduce circularity.

1875Positional correspondence. The provider’s contains an individual response 1876for each individual request that the requestor’s contained. Each individual 1877response occupies the same position within the that the corresponding 1878individual request occupied within the .

7207212bb8d0cf1f11a2b881ca263fc19f.doc Page 68 of 158 1879Processing Types. A requestor can specify whether the provider executes the individual requests 1880one-by-one in the order that they occur within a . The “processing” attribute of 1881a controls this behavior.

1882 When a specifies “processing=’sequential’”, the provider must 1883 execute each requested operation one at a time and in the exact order that it occurs within the 1884 .

1885 When a specifies “processing=’parallel’”, the provider may execute 1886 the requested operations within the in any order. 1887Individual errors. A requestor can specify whether the provider quits at the first error it encounters 1888(in processing individual requests within a ) or continues despite any number of 1889errors. The “onError” attribute of a controls this behavior.

1890 When a specifies “onError=’exit’”, the first error that a provider 1891 encounters (in processing individual operations within that batch) will result in the termination of 1892 processing for the entire batch and all of the requests that did not get processes are marked as 1893 failed. When used with the processing attribute, onError provides the RA with the ability to 1894 guarantee execution order and pre-requisite processing in batch operations.

1895 When a specifies “onError=’resume’”, the provider errors encountered 1896 processing individual operations within that batch are handles by the PSP and do not effect the 1897 attempted execution of the remaining operations in the batch. It is the responsibility of the PSP 1898 to maintain the positional correspondence of the individual operations and provide appropriate 1899 error reporting as described in section 7.3.6.

1900Overall error. When a requestor issues a with “onError=’resume’” and one 1901or more of the requests in that batch fails, then the provider will return a with 1902“status=’failure’” (even if some of the requests in that batch succeed). The requestor must 1903examine every individual response within the overall to determine which 1904requests succeeded and which requests failed.

19053.5.3.1.1 Request (normative)

1906A requestor MUST send a to a provider in order to (ask the provider to) execute 1907multiple requests as a set.

1908batchableRequest. A MAY contain any number of elements that extend 1909{spml:RequestType}.

1910A SHOULD contain at least one element that extends {spml:RequestType}.

1911A MUST NOT contain as a nested request an element that is of any the 1912following types: 1913 {spml:ListTargetsRequestType} 1914 {spmlbatch:BatchRequestType} 1915 {spmlsearch:SearchRequestType} 1916 {spmlsearch:IterateRequestType} 1917 {spmlsearch:CloseIteratorRequestType} 1918 {spmlasync:CancelRequestType} 1919 {spmlasync:StatusRequestType}

1920processing. A requestor MAY specify a “processing” attribute in a batchRequest. If a 1921requestor specifies a “processing” attribute, the value of the “processing” attribute must be one 1922of the following: ‘sequential’ or ‘parallel’.

7307212bb8d0cf1f11a2b881ca263fc19f.doc Page 69 of 158 1923 A requestor who wants the provider to process the nested requests concurrently with each 1924 other MUST specify “processing=’parallel’”. 1925 A requestor who wants the provider to process the nested requests one-by-one and in the order 1926 that they appear MAY specify “processing=’sequential’”.

1927 A requestor who does not specify “processing” is implicitly asking the provider to process the 1928 nested requests sequentially.

1929onError. A requestor MAY specify an “onError” attribute in a batchRequest. If a requestor 1930specifies an “onError” attribute, the value of the “onError” attribute must be one of the following: 1931‘exit’ or ‘resume’. 1932 A requestor who wants the provider to continue processing nested requests whenever 1933 processing one of the nested requests will result in an error MUST specify 1934 “onError=’resume’”. 1935 A requestor who wants the provider to cease processing nested requests as soon as 1936 processing any of the nested requests encounters an error MAY specify “onError=’exit’”. 1937 A requestor who does not specify an “onError” attribute implicitly asks the provider to cease 1938 processing nested requests as soon as processing any of the nested requests encounters an 1939 error.

19403.5.3.1.2 Response (normative)

1941The provider must examine the content of the . If the request is valid, the 1942provider MUST process each nested request (according to the effective “processing” and 1943“onError” settings) if the provider possibly can.

1944processing. If a specifies “processing=’parallel’”, the provider SHOULD 1945begin executing each of the nested requests as soon as possible. (Ideally, the provider would begin 1946executing all of the nested requests immediately and concurrently.) If the provider cannot begin 1947executing all of the nested requests at the same time, then the provider SHOULD begin executing 1948as many as possible of the nested requests as soon as possible.

1949If a specifies “processing=’sequential’”, the provider MUST execute 1950each of the nested requests one-by-one and in the order that each appears within the 1951. The provider MUST complete execution of each nested request before the 1952provider begins to execute the next nested request.

1953onError. The effect (on the provider’s behavior) of the “onError” attribute of a 1954depends on the “processing” attribute of the .

1955 If a specifies “onError=’exit’” and (the specifies) 1956 “processing=’sequential’” then the provider MUST NOT execute any (operation that is 1957 described by a) nested request that is subsequent to the first nested request that produces an 1958 error. 1959 1960 If the provider encounters an error in executing (the operation that is described by) a nested 1961 request, the provider MUST report the error in the nested response that corresponds to the 1962 nested request and then (the provider MUST) specify “status=’failure’” in every 1963 that corresponds to a subsequent nested request within the same 1964 . The provider MUST also specify “status=’failure’” in the overall 1965 .

7407212bb8d0cf1f11a2b881ca263fc19f.doc Page 70 of 158 1966 If a specifies “onError=’exit’” and (the specifies) 1967 “processing=’parallel’” then the provider’s behavior once an error occurs (in processing 1968 an operation that is described by a nested request) is not fully specified. 1969 1970 If the provider encounters an error in executing (the operation that is described by) a nested 1971 request, the provider MUST report the error in the nested response that corresponds to the 1972 nested request. The provider MUST also specify “status=’failure’” in the overall 1973 . However, the provider’s behavior with respect to any operation that is not 1974 yet complete is not fully specified. 1975 1976 The provider MAY stop executing any (operation that is described by a) nested request that has 1977 not yet completed or (the provider MAY) choose to complete the execution of any (operation 1978 that corresponds to a) nested request (within the same batchRequest and) for which the 1979 provider has already begun execution. The provider SHOULD NOT begin to execute any 1980 operation (that corresponds to a nested request within the same batchRequest and) for which 1981 the provider has not yet begun execution.

1982 If a specifies “onError=’resume’” and (the specifies) 1983 “processing=’parallel’”, then the provider MUST execute every (operation that is 1984 described by a) nested request within the . If the provider encounters an 1985 error in executing any (operation that is described by a) nested request, the provider MUST 1986 report the error in the nested response that corresponds to the nested request and then (the 1987 provider MUST) specify “status=’failure’” in the overall .

1988 If a specifies “onError=’resume’” and (the specifies) 1989 “processing=’sequential’”, then the provider MUST execute every (operation that is 1990 described by a) nested request within the . If the provider encounters an 1991 error in executing any (operation that is described by a) nested request, the provider MUST 1992 report the error in the nested response that corresponds to the nested request and then (the 1993 provider MUST) specify “status=’failure’” in the overall .

1994Response. The provider MUST return to the requestor a .

1995Status. The must contain a “status” attribute that indicates whether the 1996provider successfully processed every nested request. See “Status (normative)” for values of this 1997attribute. 1998 If the provider successfully executed every operation described by a) nested request, the 1999 MUST specify “status=’success’”. 2000 If the provider encountered an error in processing (the operation described by) any nested 2001 request, the MUST specify “status=’failure’”.

2002nested Responses. The MUST contain a nested response for each nested 2003request that the contains. Each nested response within the 2004corresponds positionally to a nested request within the . That is, each nested 2005response MUST appear in the same position within the that the nested request 2006(to which the nested response corresponds) originally appeared within the corresponding 2007. 2008The content of each nested response depends on whether the provider actually executed the 2009nested operation that corresponds to the nested response. 2010 Each nested response that corresponds to a nested request that the provider did not process 2011 MUST specify “status=’failed’”. (A provider might not process a nested request, for

7507212bb8d0cf1f11a2b881ca263fc19f.doc Page 71 of 158 2012 example, if the provider encountered an error processing an earlier nested request and the 2013 requestor specified both “processing=’sequential’” and “onError=’exit’”.) 2014 Each nested response that corresponds to a nested request for an operation that the provider 2015 actually executed MUST contain the same data that the provider would have returned (in the 2016 response for the corresponding operation) if the corresponding operation had been requested 2017 individually (rather than as part of a batch operation).

2018Error. If something (other than the behavior specified by the “onError“ setting with respect to 2019errors that occur in processing nested requests) prevents the provider from processing one or more 2020of the (operations described by the) nested requests within a , then the 2021 MUST have an “error” attribute that characterizes the failure. See “Error 2022(normative)” for values of this attribute.

20233.5.3.1.3 Examples (non-normative)

2024In the following example, a requestor asks a provider to perform a series of operations. The 2025requestor asks the provider first to add a Person object to one target and then to add an Account 2026object to another target. (These are the first two examples of the add operation.) [email protected]

2027The provider returns an element. The “status” of the 2028indicates that all of the nested requests were processed successfully. The 2029contains an for each that the contained. 2030Each contains the same data that it would have contained if the corresponding 2031 had been requested individually.

7607212bb8d0cf1f11a2b881ca263fc19f.doc Page 72 of 158 [email protected]

2032

7707212bb8d0cf1f11a2b881ca263fc19f.doc Page 73 of 158 2033

20343.5.4 Bulk Capability

2035The Batch Capability is defined in a schema associated with the following XML namespace: 2036urn:oasis:names:tc:SPML:2:0:bulk. This document includes the Bulk Capability XSD as 2037Appendix D. 2038The Bulk Capability defines two operations: bulkModify and bulkDelete. 2039A provider that supports the bulkModify and bulkDelete operations for a target SHOULD declare 2040that the target supports the Bulk Capability. A provider that does not support both bulkModify and 2041bulkDelete MUST NOT declare that the target supports the Bulk Capability.

20423.5.4.1 bulkModify

2043The subset of the Bulk Capability XSD that is most relevant to the bulkModify operation is shown 2044below for the convenience of the reader.

2070Modification. A MUST contain at least one . Each 2071 describes a set of changes to be applied (to every object that matches the 2072). A requestor MUST specify each for a in the 2073same way as for a . See the Modification topic within section 3.1.4.1.1.

20743.5.4.1.2 Response (normative)

2075A provider that receives a from a requestor that the provider trusts must 2076examine the content of the . If the request is valid, the provider MUST 2077apply the (set of changes described by each of the) specified elements to every 2078object that matches the specified (if the provider can possibly do so).

2079Response. The provider MUST return to the requestor a .

2080Status. The must contain a “status” attribute that indicates whether 2081the provider successfully applied every specified modification to every object that matched the 2082specified query. See “Status (normative)” for values of this attribute. 2083 If the provider successfully applied every specified modification to every object that matched 2084 the specified query, then the MUST specify “status=’success’”. 2085 If the provider encountered an error in selecting any object that matched the specified query or 2086 (if the provider encountered an error) in applying any specified modification to any of the 2087 selected objects, then the MUST specify “status=’failure’”. 2088Error. If the provider was unable to apply the specified modification to every object that matched 2089the specified query, then the MUST have an “error” attribute that 2090characterizes the failure. See “Error (normative)” for values of this attribute. 2091The section entitled "SearchQueryType Errors (normative)" describes errors specific to a request 2092that contains a .

20933.5.4.1.3 Examples (non-normative)

2094In the following example, a requestor asks a provider to change every Person with an email 2095address matching [email protected] to have instead an email address of [email protected].

7907212bb8d0cf1f11a2b881ca263fc19f.doc Page 75 of 158 path=”/Person/email=’[email protected]’”/> 2100In the following example, a requestor asks a provider to remove the “owner” of any account that is 2101currently owned by “joebob”. The requestor uses as a selection criterion the query 2102clause that the Reference Capability defines. 2103NOTE: The logic required to modify a reference may depend on the cardinality that is defined for 2104that type of reference. See Reference Capability below.

21083.5.4.2 bulkDelete

2109The subset of the Bulk Capability XSD that is most relevant to the bulkDelete operation follows.

8007212bb8d0cf1f11a2b881ca263fc19f.doc Page 76 of 158 type="spmlbulk:BulkDeleteRequestType”/>

2120recursive. A MAY have a “recursive” attribute that indicates 2121whether the provider should delete the specified object along with any other object it contains. 2122(Unless the specifies “recursive=’true’”, a provider will not delete 2123an object that contains other objects.)

21243.5.4.2.2 Response (normative)

2125A provider that receives a from a requestor that the provider trusts must 2126examine the content of the . If the request is valid, the provider MUST 2127delete every object that matches the specified (if the provider can possibly do so).

2128recursive. A provider MUST NOT delete any object that contains other objects unless the 2129 specifies “recursive=’true’”.

2130 If the specifies “recursive=’true’”, 2131 then the provider MUST delete every object that matches the specified query 2132 along with any object that a matching object (directly or indirectly) contains.

2133 If the specifies “recursive=’false’” 2134 (or if the omits the “recursive” attribute”) 2135 and at least one object that matches the specified query contains another object, 2136 then the provider MUST NOT delete any of the objects that match the specified query. 2137 In this case, the provider’s response must return an error (see below).

2138Response. The provider MUST return to the requestor an .

2139Status. The must contain a “status” attribute that indicates whether 2140the provider successfully deleted every object that matched the specified query. See “Status 2141(normative)” for values of this attribute. 2142 If the provider successfully deleted every object that matched the specified query, the 2143 MUST specify “status=’success’”. 2144 If the provider encountered an error in selecting any object that matched the specified query or 2145 (if the provider encountered an error) in deleting any of the selected objects, the 2146 MUST specify “status=’failure’”.

8107212bb8d0cf1f11a2b881ca263fc19f.doc Page 77 of 158 2147Error. If the provider was unable to delete every object that matched the specified query, then the 2148 MUST have an “error” attribute that characterizes the failure. See 2149“Error (normative)” for values of this attribute. 2150The section entitled "SearchQueryType Errors (normative)" describes errors specific to a request 2151that contains a . Also see the section entitled “SelectionType Errors (normative)”. 2152If at least one object that matches the specified query contains another object 2153and the does NOT specify “recursive=’true’”, 2154then the provider’s response should specify “error=’invalidContainment’”.

21553.5.4.2.3 Examples (non-normative)

2156In the following example, a requestor asks a provider to delete every Person with an email address 2157matching [email protected]. 2158The provider returns a . The “status” attribute of the 2159 indicates that the provider successfully executed the bulkDelete 2160operation. 2161In the following example, a requestor asks a provider to delete any account that is currently owned 2162by “joebob”. The requestor uses as a selection criterion the query clause that the 2163Reference Capability defines. 2164The provider returns a . The “status” attribute of the 2165 indicates that the provider successfully executed the bulkDelete 2166operation.

8207212bb8d0cf1f11a2b881ca263fc19f.doc Page 78 of 158 21673.5.5 Password Capability

2168The Password Capability is defined in a schema that is associated with the following XML 2169namespace: urn:oasis:names:tc:SPML:2:0:password. This document includes the 2170Password Capability XSD as Appendix E. 2171The Password Capability defines four operations: ‘setPassword, ‘expirePassword’, ‘resetPassword’ 2172and ‘validatePassword’. 2173 The ‘setPassword’ operation changes to a specified value the password that is associated with 2174 a specified object. The ‘setPassword’ allows a requestor to supply the current password (in 2175 case the target system or application requires it). 2176 The ‘expirePassword’ operation marks as no longer valid the password that is associated with a 2177 specified object. (Most systems or applications will require a user to change an expired 2178 password on the next login.) 2179 The ‘resetPassword’ operation changes to an unspecified value the password that is associated 2180 with a specified object. The ‘resetPassword’ operation returns the new password. 2181 The ‘validatePassword’ operation tests whether a specified value would be valid as the 2182 password for a specified object. (The ‘validatePassword’ operation allows a requestor to test a 2183 password value against the password policy for a system or application.) 2184A provider that supports the setPassword, expirePassword, resetPassword and validatePassword 2185operations for a target SHOULD declare that the target supports the Password Capability. A 2186provider that does not support all of the setPassword, expirePassword, resetPassword and 2187validatePassword operations MUST NOT declare that the target supports the Password Capability.

21883.5.5.1 setPassword

2189The setPassword operation enables a requestor to specify a new password for an object. 2190The subset of the Password Capability XSD that is most relevant to the setPassword operation 2191follows.

8307212bb8d0cf1f11a2b881ca263fc19f.doc Page 79 of 158 21923.5.5.1.1 Request (normative)

2193A requestor MUST send a to a provider in order to (ask the provider to) 2194change to a specified value the password that is associated an existing object.

2195Execution. A MAY specify a type of execution. See Determining 2196execution type.

2197psoID. A MUST contain exactly one element. A 2198element MUST identify an object that exists on a target (that is supported by the provider). See the 2199section entitled "PSO Identifier (normative)".

2200password. A MUST contain exactly one element. A 2201 element MUST contain a string value.

2202currentPassword. A MAY contain at most one 2203element. A element MUST contain a string value.

22043.5.5.1.2 Response (normative)

2205A provider that receives a from a requestor that the provider trusts 2206MUST examine the content of the . If the request is valid and if the 2207specified object exists, then the provider MUST enable the object that is specified by the .

2208Execution. If an does not have an execution attribute, the provider 2209MUST choose a type of execution for the requested operation. See the section entitled 2210“Determining execution type”.

2211Response. The provider must return to the requestor a . The 2212 must have a “status” attribute that indicates whether the provider 2213successfully enabled the specified object. See “Status (normative)” for values of this attribute.

2214Error. If the provider cannot change (to the value that the “password” attribute specifies) the 2215password that is associated with the requested object, the must 2216contain an “error” attribute that characterizes the failure. See “Error (normative)” for values of 2217this attribute. 2218The provider MUST return an error if any of the following is true:

2219 The contains a for an object that does not exist. 2220 The target system or application will not accept (as the new password) the value that a 2221 specifies for the “password” attribute. 2222 The target system or application requires the current password in order to change the password 2223 and a specifies no value for the “currentPassword” attribute. 2224 The target system or application requires the current password in order to change the password 2225 and the target system or application will not accept (as the current password) the value that a 2226 specifies for the “currentPassword” attribute. 2227 The target system or application returns an error (or throws an exception) when the provider 2228 tries to set the password.

22293.5.5.1.3 Examples (non-normative)

2230In the following example, a requestor asks a provider to set the password for a Person object.

8407212bb8d0cf1f11a2b881ca263fc19f.doc Page 80 of 158 y0baby corvette 2231The provider returns an element. The “status” attribute of the 2232 element indicates that the provider successfully changed the 2233password.

22343.5.5.2 expirePassword

2235The expirePassword operation enables a requestor to mark as invalid the current password for an 2236object. 2237The subset of the Password Capability XSD that is most relevant to the expirePassword operation 2238follows.

22393.5.5.2.1 Request (normative)

2240A requestor MUST send a to a provider in order to (ask the provider 2241to) mark as no longer valid the password that is associated an existing object.

2242Execution. A MAY specify a type of execution. See Determining 2243execution type.

2244psoID. A MUST contain exactly one element. A 2245element MUST identify an object that exists on a target (that is supported by the provider). See the 2246section entitled "PSO Identifier (normative)".

2247remainingLogins. A MAY have a “remainingLogins” attribute 2248that specifies a number of grace logins that the target system or application should permit.

22493.5.5.2.2 Response (normative)

2250A provider that receives a from a requestor that the provider trusts 2251MUST examine the content of the . If the request is valid and if the

8507212bb8d0cf1f11a2b881ca263fc19f.doc Page 81 of 158 2252specified object exists, then the provider MUST mark as no longer valid the password that is 2253associated with the object that is specified by the .

2254Execution. If an does not have an execution attribute, the 2255provider MUST choose a type of execution for the requested operation. See the section entitled 2256“Determining execution type”.

2257Response. The provider must return to the requestor an . The 2258 must have a “status” attribute that indicates whether the 2259provider successfully enabled the specified object. See “Status (normative)” for values of this 2260attribute. 2261Error. If the provider cannot mark as no longer valid the password that is associated with the 2262requested object, the must contain an “error” attribute that 2263characterizes the failure. See “Error (normative)” for values of this attribute. 2264The provider MUST return an error if any of the following is true:

2265 The contains a for an object that does not exist. 2266 The target system or application will not accept (as the number of grace logins to permit) the 2267 value that a specifies for the “remainingLogins” attribute. 2268 The target system or application returns an error (or throws an exception) when the provider 2269 tries to mark as no longer valid the password that is associated with the specified object.

22703.5.5.2.3 Examples (non-normative)

2271In the following example, a requestor asks a provider to expire the password for a Person object. 2272The provider returns an element. The “status” attribute of the 2273 element indicates that the provider successfully expired the 2274password.

22753.5.5.3 resetPassword

2276The resetPassword operation enables a requestor to change (to an unspecified value) the 2277password for an object and to obtain that newly generated password value. 2278The subset of the Password Capability XSD that is most relevant to the resetPassword operation is 2279shown below for the convenience of the reader.

8607212bb8d0cf1f11a2b881ca263fc19f.doc Page 82 of 158

22803.5.5.3.1 Request (normative)

2281A requestor MUST send a to a provider in order to (ask the provider 2282to) change the password that is associated an existing object and to (ask the provider to) return to 2283the requestor the new password value.

2284Execution. A MAY specify a type of execution. See Determining 2285execution type.

2286psoID. A MUST contain exactly one element. A 2287element MUST identify an object that exists on a target (that is supported by the provider). See the 2288section entitled "PSO Identifier (normative)".

22893.5.5.3.2 Response (normative)

2290A provider that receives a from a requestor that the provider trusts 2291MUST examine the content of the . If the request is valid and if the 2292specified object exists, then the provider MUST change the password that is associated with the 2293object that is specified by the and must return to the requestor the new password value.

2294Execution. If an does not have an execution attribute, the provider 2295MUST choose a type of execution for the requested operation. See the section entitled 2296“Determining execution type”.

2297Response. The provider must return to the requestor a . The 2298 must have a “status” attribute that indicates whether the provider 2299successfully changed the password that is associated with the specified object and successfully 2300returned to the requestor the new password value. See “Status (normative)” for values of this 2301attribute. 2302If the provider knows that the provider will not be able to return to the requestor the new password 2303value, then the provider MUST NOT change the password that is associated with the specified 2304object. (To do so would create a state that requires manual administrator intervention, and this 2305defeats the purpose of the ‘resetPassword’ operation.)

2306password. The MAY contain a element. If the 2307 contains a element, the element must 2308contain the newly changed password value that is associated with the specified object. 2309Error. If the provider cannot change the password that is associated with the specified object, or if 2310the provider cannot return the new password attribute value to the requestor, then the

8707212bb8d0cf1f11a2b881ca263fc19f.doc Page 83 of 158 2311 must contain an “error” attribute that characterizes the failure. 2312See “Error (normative)” for values of this attribute. 2313The provider MUST return an error if any of the following is true:

2314 The contains a for an object that does not exist. 2315 The target system or application will not allow the provider to return to the requestor the new 2316 password value. (If the provider knows this to be the case, then the provider MUST NOT 2317 change the password that is associated with the specified object. See above.) 2318 The target system or application returns an error (or throws an exception) when the provider 2319 tries to change the password that is associated with the specified object or (when the provider) 2320 tries to obtain the new password value.

23213.5.5.3.3 Examples (non-normative)

2322In the following example, a requestor asks a provider to reset the password for a Person object. 2323The provider returns an element. The “status” attribute of the 2324 indicates that the provider successfully reset the password. gener8ed

23253.5.5.4 validatePassword

2326The validatePassword operation enables a requestor to determine whether a specified value would 2327be valid as the password for a specified object. 2328The subset of the Password Capability XSD that is most relevant to the validatePassword operation 2329follows.

8807212bb8d0cf1f11a2b881ca263fc19f.doc Page 84 of 158

23303.5.5.4.1 Request (normative)

2331A requestor MUST send a to a provider in order to (ask the 2332provider to) test whether a specified value would be valid as the password that is associated with 2333an existing object.

2334Execution. A MAY specify a type of execution. See the section 2335entitled “Determining execution mode”.

2336psoID. A MUST contain exactly one element. A 2337 element MUST identify an object that exists on a target (that is supported by the 2338provider). See the section entitled "PSO Identifier (normative)".

2339password. A MUST contain exactly one element. 2340A element MUST contain a string value.

23413.5.5.4.2 Response (normative)

2342A provider that receives a from a requestor that the provider 2343trusts MUST examine the content of the . If the request is valid 2344and if the specified object exists, then the provider MUST test whether the specified value would be 2345valid as the password that is associated with the object that is specified by the .

2346Execution. If an does not have an execution attribute, the 2347provider MUST choose a type of execution for the requested operation. See the section entitled 2348Determining execution mode”.

2349Response. The provider must return to the requestor a . The 2350 must have a “status” attribute that indicates whether the 2351provider successfully changed the password that is associated with the specified object and 2352successfully returned to the requestor the new password value. See “Status (normative)” for values 2353of this attribute. 2354If the provider knows that the provider will not be able to return to the requestor the new password 2355value, then the provider MUST NOT change the password that is associated with the specified 2356object. (To do so would create a state that requires manual administrator intervention, and this 2357defeats the purpose of the ‘validatePassword’ operation.)

2358valid. The MUST have a “valid” attribute that indicates 2359whether the (content that was specified in the ) 2360would be valid as the password that is associated with the specified object. 2361Error. If the provider cannot determine whether the specified value would be valid as the password 2362that is associated with the specified object, then the must 2363contain an “error” attribute that characterizes the failure. See “Error (normative)” for values of 2364this attribute. 2365The provider MUST return an error if any of the following is true:

2366 The contains a for an object that does not exist.

8907212bb8d0cf1f11a2b881ca263fc19f.doc Page 85 of 158 2367 The target system or application returns an error (or throws an exception) when the provider 2368 tries to determine whether the specified value would be valid as the password that is associated 2369 with the specified object.

23703.5.5.4.3 Examples (non-normative)

2371In the following example, a requestor asks a provider to validate a value as a password for a 2372Person object. y0baby 2373The provider returns an element. The “status” attribute of 2374the indicates that the provider successfully tested whether the 2375 value specified in the request would be valid as the password that is associated with 2376the specified object. The specifies “valid=’true’”, which 2377indicates that the specified value would be valid as the password that is associated with the 2378specified object.

9007212bb8d0cf1f11a2b881ca263fc19f.doc Page 86 of 158 2379

23803.5.6 Reference Capability

2381The Reference Capability is defined in a schema that is associated with the following XML 2382namespace: urn:oasis:names:tc:SPML:2:0:reference. This document includes the 2383Reference Capability XSD as Appendix F.

9107212bb8d0cf1f11a2b881ca263fc19f.doc Page 87 of 158 type="spmlref:ReferenceDefinitionType"/>

2384The Reference Capability defines no operation. Instead, the Reference Capability allows a provider 2385to declare, as part of each target, which types of objects support references to which other types of 2386objects. The XML representations of references flow through the core operations as capability- 2387specific data. 2388 In order to create an object with references, a requestor specifies capability-specific data to the 2389 core ‘add’ operation. 2390 In order to add, remove or replace references to an object, a requestor specifies capability- 2391 specific data to the core ‘modify’ operation. 2392 In order to obtain references for an object, a requestor examines capability-specific data 2393 returned as output by the core ‘add’, ‘lookup’ and ‘search’ operations. 2394Motivation. Defining a standard capability for references is important for several reasons. 2395 Managing references to other objects can be a very important part of managing objects. 2396 Object references to other objects present a scalability problem. 2397 Object references to other objects present an integrity problem. 2398Provisioning systems must often list, create, and delete connections between objects 2399in order to manage the objects themselves. In some cases, a provisioning system 2400must manage data that is part a specific connection (e.g., in order to specify 2401the expiration of a user’s membership in a group) – see the discussion of “Reference Data” below. 2402Because connections to other objects can be very important, it is important to be able to represent 2403such connections generically (rather than as something specific to each target schema). 2404The reference capability enables a requestor to manage an object’s references independent of the 2405object’s schema. This is particularly important in the cases where a provider allows references to 2406span targets. For example, a provisioning system must often maintain knowledge about which 2407Persons own which accounts. In such cases, an Account object (that is contained by one target) 2408may refer to a Person object (that is contained by another target) as its owner. 2409Scale is another significant aspect of references. The number of connections between objects may 2410be an order of magnitude more than the number of objects themselves. Unconditionally including 2411reference information in the XML representation of each object could greatly increase the size of 2412that object’s XML representation. Imagine, for example, that each Account may refer to multiple 2413Groups (or that a Group may refer to each of its members). 2414Defining reference as an optional capability (and allowing references to be omitted from each 2415object’s schema) does two things. First, this allows a requestor to exclude an object’s references 2416from the XML representation of each object (since a requestor can control which capability-specific 2417data are included). Second, this allows providers to manage references separately from schema- 2418defined attributes (which may help a provider cope with the scale of connections). 2419The ability to manage references separately from schema-defined data may also help providers to 2420maintain the integrity of references. In the systems and applications that underly many provisioning 2421target, deleting an object A may not delete another object B’s reference to object A. Allowing a 2422provider to manage references separately allows the provider to control such behavior (and 2423perhaps even to prevent the deletion of object A when another object B still refers to object A).

9207212bb8d0cf1f11a2b881ca263fc19f.doc Page 88 of 158 24243.5.6.1 Reference Definitions

2425Reference Definitions. A provider declares each type of reference that a particular target supports 2426(or declares each type of reference that a particular supported schema entity on a target supports) 2427as an instance of reference definition.

2428A provider’s contains a list of targets that the provider exposes for 2429provisioning. Part of each target declaration is the set of capabilities that the target supports. Each 2430capability refers (by means of its “namespaceURI” attribute) to a specific capability. Any 2431 element that refers to the Reference Capability MAY contain (as open content) any 2432number of reference definitions. 2433Each reference definition names a specific type of reference and also specifies the following: 2434 which schema entity (on the target that contains the capability element that contains the 2435 reference definition) can refer 2436 to which schema entity (on which target). 2437For normative specifics, see the “Reference Capability declarations” topic within the listTargets 2438section. 2439Overlap. Any number of reference definitions may declare different “from- and to-” entity pairs for 2440the same type of reference. For example, a reference definition may declare that an Account may 2441refer to a Person as its “owner”. Another reference definition may declare that an 2442OrganizationalUnit may refer to a Person as its “owner”. SPMLv2 specifies the mechanism--but 2443does not define the semantics--of reference. 2444Direction. Each reference definition names a specific type of reference and specifies which 2445schema entity (on which target?) can refer to which schema entity (on which target?). Any number 2446of reference definitions may define “from- and to-” entity pairs for the same type of reference. 2447No Inverse. A standard SPMLv2 reference definition specifies nothing about an inverse 2448relationship. For example, a reference definition that says an Account may refer to a Person as its 2449“owner” does NOT imply that a Person may refer to Account. 2450Nothing prevents a provider from declaring (by means of a reference definition) that Person may 2451refer to Account in a type of reference called “owns”, but nothing (at the level of this specification) 2452associates these two types of references to say that “owns” is the inverse of “owner”. 2453No Cardinality. A reference definition specifies no restrictions on the number of objects to which an 2454object may refer (by means of that defined type of reference). Thus, for example, an Account may 2455refer to multiple Persons as its “owner”. This may be logically incorrect, or this may not be the 2456desired behavior, but SPMLv2 does not require a provider to support restrictions on the cardinality 2457of a particular type of reference. 2458In general, a requestor must assume that each defined type of reference is optional and many-to- 2459many. This is particularly relevant when a requestor wishes to modify references. A requestor 2460SHOULD NOT assume that a reference that the requestor wishes to modify is the object’s only 2461reference of that type. A requestor also SHOULD NOT assume that a reference from one object to 2462another object that the requestor wishes to modify is the only reference between the two objects. 2463Although this may seem perverse, SPMLv2 allows one object “A” to have more than one reference 2464of the same type to the same object “B”. 2465ReferenceDataType. A reference definition may be complex, which means that an instance of that 2466type of reference may have reference data associated with it. See the section entitled “Complex 2467References” below. 2468The definition of a type of reference that is complex must contain a for each 2469possible structure of reference data. Each element refers to a specific entity

9307212bb8d0cf1f11a2b881ca263fc19f.doc Page 89 of 158 2470in a target schema. A element (within an instance of that type of reference) may 2471contain one element of any of these types. 2472A reference definition that contains no sub-element indicates that the type of 2473reference it defines does not support reference data. 2474For a normative description, see the “ReferenceDefinition referenceDataType” topic within the 2475section that describes listTargetsResponse.

24763.5.6.2 References

2477Reference Data. SPMLv2 allows each reference (i.e., each instance of ReferenceType) to contain 2478additional reference data. Most references between objects require no additional data, but this 2479supports cases in which a reference from one object to another may carry additional information “on 2480the arrow” of the relationship. For example, a RACF user’s membership in a particular RACF group 2481carries with it the additional information of whether that user has the ADMINISTRATOR or 2482SPECIAL privilege within that group. Several other forms of group membership carry with them 2483additional information about the member’s expiration. See the section entitled “Complex 2484References” below. 2485Search. A requestor can search for objects based on reference values using the 2486 query clause. The {HasReferenceType} extends {QueryClauseType}, 2487which indicates that an instance of {HasReferenceType} can be used to select objects. A 2488 clause matches an object if and only if the object has a reference that matches 2489every specified component (i.e., element or attribute) of the element. 2490See the examples within section entitled “Search”.

24913.5.6.3 Complex References

2492The vast majority of reference types are simple: that is, one object’s reference to another object 2493carries no additional information. However certain types of references may support additional 2494information that is specific to a particular reference. For example, when a user is assigned to one 2495or more Entrust GetAccess Roles, each role assignment has a start date and an end date. We 2496describe a reference that contains additional data (that is specific to the reference) as “complex”. 2497Example: RACF Group Membership is another example of a complex type of reference. Each 2498RACF group membership carries with it additional data about whether the user has the SPECIAL, 2499AUDITOR, or OPERATIONS privileges in that group. 2500 Group-SPECIAL gives a group administrator control over all profiles within the group 2501 Group-AUDITOR allows a user to monitor the use of the group's resources 2502 Group-OPERATIONS allows a user to perform maintenance operations 2503 on the group's resources 2504For purposes of this example, let us represent these three group-specific privileges as attributes of 2505an XML type called “RacfGroupMembershipType”. Suppose that the XML Schema for such a type 2506looks like the following:

9407212bb8d0cf1f11a2b881ca263fc19f.doc Page 90 of 158

2507 2508The following subsections describe several different ways to model RACF Group Membership. The 2509fictional is the same in all of the examples. In each subsection, however, the 2510provider’s definition varies with the approach.

25113.5.6.3.1 Using Reference Data

2512The simplest way to model a complex reference such as RACF Group membership is to represent 2513the additional information as arbitrary reference data. The element within a 2514 may contain any data. 2515The following example shows how a provider’s listTargetsResponse might reflect this approach. 2516The sample schema for the “RACF” target is very simple (for the sake of brevity). The provider 2517defines a type of reference called “memberOfGroup”. Within a of this type, the 2518 element must contain exactly one element (and 2519should contain nothing else).

9507212bb8d0cf1f11a2b881ca263fc19f.doc Page 91 of 158 ReferenceData for a “memberOfGroup” reference must contain exactly one racfGroupMembership element. 2520Manipulating Reference Data. The only way to manipulate the reference data associated with a 2521complex reference is by using the modify operation that is part of the Core XSD. A requestor may 2522add, replace or delete any capability-specific data that is associated with an object. 2523Capabilities Do Not Apply. SPML specifies no way to apply a capability-specific operation to a 2524reference. Thus, for example, one can neither suspend nor resume a reference. This is because 2525even a reference is not a provisioning service object. A reference is instead capability-specific data 2526that is associated with an object. 2527You can think of a reference (or any item of capability-specific data) that is associated with an 2528object as an “extra” attribute or as a sub-element of the object. The provider supports each “extra” 2529(attribute or sub-element) data independent of the schema of the target that contains the object. 2530The provider keeps all separate from the regular schema-defined 2531within each .

25323.5.6.3.2 Relationship Objects

2533The fact that capabilities cannot apply to references does not prevent a provider from offering this 2534kind of rich function. There is an elegant way to represent a complex relationship that allows a 2535requestor to operate directly on the relationship itself. A provider may model a complex relationship 2536between two objects as a third object that refers to each of the first two objects. 2537This approach is analogous to a “linking record” in relational database design. In the “linking 2538record” approach, the designer “normalizes” reference relationships into a separate table. Each 2539row in a third table connects a row from one table to a row in another table. This approach allows 2540each relationship to carry additional information that is specific to that relationship. Data specific to 2541each reference are stored in the columns of the third table. Even when relationships do not need to 2542carry additional information, this approach is often used when two objects may be connected by 2543more than one instance of the same type of relationship, or when relationships are frequently added 2544or deleted and referential integrity must be maintained. 2545Rather than have an object A refer to an object B directly, a third object C refers to object A and to 2546object B. Since object C represents the relationship itself, object C refers to object A as its 2547“fromObject” and object C refers to object B as its “toObject”. 2548A provider that wants to treat each instance of a (specific type of) relationship as an object does so 2549by defining a schema entity to contain the additional information (specific to that type of 2550relationship) in the schema for a target. The provider then declares two types of references that 2551apply to that schema entity: a “fromObject” type of reference and a “toObject” type of reference. 2552The provider may also declare that certain capabilities apply to that schema entity. This model 2553allows a requestor to operate conveniently on each instance of a complex relationship.

9607212bb8d0cf1f11a2b881ca263fc19f.doc Page 92 of 158 2554For example, suppose that a provider models as a schema entity a type of relationship that has an 2555effective date and has an expiration date. As a convenience to requestors, the provider might 2556declare that this schema entity (that is, the “linking” entity) supports the Suspend Capability. The 2557‘suspend’ and ‘resume’ operations could manipulate the expiration date and the effective date 2558without the requestor having to understand the structure of that schema entity. This convenience 2559could be very valuable where the attribute values or element content that are manipulated have 2560complex syntax, special semantics or implicit relationships with other elements or attributes. 2561The following example shows how a provider’s listTargetsResponse might reflect this approach. 2562The sample schema for the “RACF” target is very simple (for the sake of brevity). Each instance of racfGroupMembership refers to one racfUserProfile and refers to one racfGroupProfile.

9707212bb8d0cf1f11a2b881ca263fc19f.doc Page 93 of 158 2563Variations. Naturally, many variations of this approach are possible. For example, an instance of 2564RacfUserProfile could refer to an instance of RacfGroupMembership (rather than having an 2565instance of RacfGroupMembership refer to both RacfUserProfile and an instance of 2566RacfGroupProfile). However, such a variation would not permit an instance of RacfUserProfile to 2567refer to more than one group (and could result in an orphaned relationship objects unless the 2568provider carefully guards against this).

25693.5.6.3.3 Bound Relationship Objects

2570One robust variation of independent relationship objects is to bind each relationship object beneath 2571one of the objects it connects. For example, one could bind each instance of 2572RacfGroupMembership beneath the instance of RacfUserProfile that would otherwise be the 2573“fromUser”. That way, deleting an instance of RacfUserProfile also deletes all of its 2574RacfGroupMemberships. This modeling approach makes clear that the relationship belongs with 2575the “fromObject” and helps to prevent orphaned relationship objects. 2576The next example illustrates bound relationship objects. Any number of racfGroupMembership objects may be bound beneath a racfUserProfile object.

9807212bb8d0cf1f11a2b881ca263fc19f.doc Page 94 of 158 Each racfGroupMembership is bound beneath a racfUserProfile and refers to one racfGroupProfile.

9907212bb8d0cf1f11a2b881ca263fc19f.doc Page 95 of 158 25773.5.7 Search Capability

2578The Search Capability is defined in a schema associated with the following XML namespace: 2579urn:oasis:names:tc:SPML:2:0:search. This document includes the Search Capability XSD 2580as Appendix G. 2581The Search Capability defines two operations: search and iterate. The search and iterate 2582operations together allow a requestor to obtain in a scalable manner the XML representation of 2583every object that matches specified selection criteria. The search operation returns in its response a 2584first set of matching objects. Each iterate operation returns more matching objects. 2585A provider that supports the search and iterate operations for a target SHOULD declare that the 2586target supports the Search Capability. A provider that does not support both search and iterate 2587MUST NOT declare that the target supports the Search Capability.

2588Resource considerations. A provider must limit the size and duration of its search results (or that 2589provider will exhaust available resources). A provider must decide: 2590 How large of a search result the provider will select on behalf of a requestor. 2591 How large of a search result the provider will queue on behalf of a requestor 2592 (so that the requestor may iterate the search results). 2593 For how long a time the provider will queue a search result on behalf of a requestor.

2594These decisions may be governed by the provider’s implementation, by its configuration, or by 2595runtime computation.

2596A provider that wishes to never to queue search results may return every matching object (up to the 2597provider’s limit and up to any limit specified by the requestor) in the search response. Such a 2598provider would never return an iterator, and would not need to support the iterate operation. The 2599disadvantage is that, without an iterate operation, a provider’s search capability either is limited to 2600small results or produces large search responses.

2601A provider that wishes to support the iterate operation must store (or somehow queue) the objects 2602selected by a search operation until the requestor has a chance to iterate those results. (That is, a 2603provider must somehow queue the objects that matched the criteria of a search operation and that 2604were not returned in the search response.)

2605If all goes well, the requestor will continue to iterate the search result until all of the objects have 2606been sent to the requestor. This allows the provider to free any resource that is still associated with 2607the search result. However, if something goes wrong (or if the requestor changes its mind) the 2608requestor may not iterate the search result in a timely manner. In fact, the requestor may never 2609iterate the search result completely.

2610A provider cannot queue search results indefinitely. The provider must eventually release the 2611resources associated with a search result. (Put differently, a provider must eventually expire any 2612iterator that the provider returns to a requestor.) Otherwise, the provider may run out of resources.

2613Providers should carefully manage the resources associated with search results. For example:

2614 A provider may define a timeout interval that specifies the maximum time between iterate 2615 requests. If a requestor does not request an iterate operation within this interval, the provider 2616 will release the resources associated with the search result. This invalidates any iterator that 2617 represents this search result.

10007212bb8d0cf1f11a2b881ca263fc19f.doc Page 96 of 158 2618 A provider may also define an overall result lifetime that specifies the maximum length of time 2619 to retain a search result. After this amount of time has passed, the provider will release the 2620 search result.

2621 A provider may also wish to enforce an overall limit on the resources available to queue search 2622 results, and to adjust its behavior (or even to refuse search requests) accordingly.

2623 To prevent denial of service attacks, the provider should not allocate any resource on behalf of 2624 a requestor until that requestor is properly authenticated (see the section entitled “Security and 2625 Privacy Considerations”).

26263.5.7.1 search

2627The search operation obtains every object that matches a specified query. 2628The subset of the Search Capability XSD that is most relevant to the search operation follows.

10107212bb8d0cf1f11a2b881ca263fc19f.doc Page 97 of 158 use="optional" default="everything"/>

2629The is the same type of element that is specified as part of a or 2630a . See the section entitled "SearchQueryType".

2631If the search operation is successful but selects no matching object, the will 2632not contain a . 2633If the search operation is successful and selects at least one matching object, the 2634 will contain any number of elements, each of which represents a 2635matching object. If the search operation selects more matching objects than the 2636 contains, the will also contain an that the 2637requestor can use to retrieve more matching objects. (See the ‘iterate’ operation below.) 2638If a search operation would select more objects than the provider can queue for subsequent 2639iteration by the requestor, the provider's will specify 2640"error='insufficientResources'". 2641Search is not batchable. For reasons of scale, neither ‘search’ nor ‘iterate’ should be nested in a 2642batch request. When a search query matches matches more objects than the provider can place 2643directly in the response, the provider must temporarily store the remaining objects. Storing the 2644remaining objects allows allows the requestor to iterate the remaining objects, but also requires the 2645provider to commit resources. See the “Resource Considerations” topic earlier in this Search 2646Capability section. 2647Batch responses also tend to be large. Batch operations are typically asynchronous, so storing the 2648results of asynchronous batch operations imposes on providers a resource burden similar to that of 2649search results. Allowing a requestor to nest a search request within a batch request would 2650aggravate the resource problem, requiring a provider to store more information in larger chunks for 2651a longer amount of time.

26523.5.7.1.1 Request (normative)

2653A requestor MUST send a to a provider in order to (ask the provider to) obtain 2654every object that matches specified selection criteria.

10207212bb8d0cf1f11a2b881ca263fc19f.doc Page 98 of 158 2655Execution. A MAY specify a type of execution. See the section entitled 2656“Determining execution mode”.

2657query. A MUST contain exactly one element. A describes 2658criteria that (the provider must use to) select objects on a target. 2659See the section entitled "SearchQueryType in a Request (normative)".

2660ReturnData. A MAY have a “returnData” attribute that tells the provider 2661which types of data to include in each selected object. 2662 A requestor that wants the provider to return nothing of the added object 2663 MUST specify “returnData=’nothing’”. 2664 A requestor that wants the provider to return only the identifier of the added object 2665 MUST specify “returnData=’identifier’”. 2666 A requestor that wants the provider to return the identifier of the added object 2667 plus the XML representation of the object (as defined in the schema of the target) 2668 MUST specify “returnData=’data’”. 2669 A requestor that wants the provider to return the identifier of the added object 2670 plus the XML representation of the object (as defined in the schema of the target) 2671 plus any capability-specific data that is associated with the object 2672 MAY specify “returnData=’everything’” or MAY omit the “returnData” attribute 2673 (since “returnData=’everything’” is the default).

2674maxSelect. A MAY have a “maxSelect” attribute. The value of the 2675“maxSelect” attribute specifies the maximum number of objects to select.

2676IncludeDataForCapability. A MAY contain any number of 2677 elements. Each element 2678specifies a capability for which the provider should return capability-specific data (unless the 2679“returnData” attribute specifies that the provider should return no capability-specific data at all). 2680 A requestor that wants the provider to return (as part of each object) capability-specific data for 2681 only a certain set of capabilities MUST enumerate that set of capabilities (by including an 2682 element that specifies each such capability) in the 2683 . 2684 A requestor that wants the provider to return (as part of each object) capability-specific data for 2685 all capabilities MUST NOT include an element in the 2686 . 2687 A requestor that wants the provider to return no capability-specific data MUST specify an 2688 appropriate value for the “returnData” attribute. See the section entitled “ReturnData” 2689 immediately previous.

26903.5.7.1.2 Response (normative)

2691A provider that receives a from a requestor that the provider trusts must 2692examine the content of the . If the request is valid, the provider MUST return 2693(the XML that represents) every object that matches the specified (if the provider can 2694possibly do so). However, the number of objects selected (for immediate return or for eventual 2695iteration) MUST NOT exceed any limit specified as “maxSelect” in the .

2696Execution. If an does not have an “execution” attribute, the provider 2697MUST choose a type of execution for the requested operation. See the section entitled 2698“Determining execution mode”.

10307212bb8d0cf1f11a2b881ca263fc19f.doc Page 99 of 158 2699A provider SHOULD execute a search operation synchronously if it is possible to do so. (The 2700reason for this is that the result of a search should reflect the current state of each matching object. 2701Other operations are more likely to intervene if a search operation is executed asynchronously.)

2702Response. The provider MUST return to the requestor a .

2703Status. The must contain a “status” attribute that indicates whether the 2704provider successfully selected every object that matched the specified query. See “Status 2705(normative)” for values of this attribute. 2706 If the provider successfully returned (the XML that represents) every object that matched the 2707 specified up to any limit specified by the value of the “maxSelect” attribute, then the 2708 MUST specify “status=’success’”.

2709 If the provider encountered an error in selecting any object that matched the specified 2710 or (if the provider encountered an error) in returning (the XML that represents) any of the 2711 selected objects, then the MUST specify “status=’failure’”.

2712Pso. The MAY contain any number of elements.

2713 If the specifies “status=’success’” and at least one object matched 2714 the specified , then the MUST contain at least one 2715 element that contains the (XML representation of the) a matching object.

2716 If the specifies “status=’success’” and no object matched the 2717 specified , then the MUST NOT contain a element.

2718 If the specifies “status=’failure’”, then the 2719 MUST NOT contain a element.

2720PSO and ReturnData. Each contains the subset of (the XML representation of) a requested 2721object that the “returnData” attribute of the specified. By default, each 2722 contains the entire (XML representation of an) object.

2723 A element MUST contain a element. 2724 The element MUST contain the identifier of the requested object. 2725 See the section entitled “PSO Identifier (normative)”.

2726 A element MAY contain a element. 2727 - If the specified “returnData=’identifier’”, 2728 then the MUST NOT contain a element. 2729 - Otherwise, if the specified “returnData=’data’” 2730 or (if the specified) “returnData=’everything’” 2731 or (if the ) omitted the “returnData” attribute 2732 then the element MUST contain the XML representation of the object. 2733 This XML must be valid according to the schema of the target for the schema entity of 2734 which the newly created object is an instance.

2735 A element MAY contain any number of elements. Each 2736 element contains an item of capability-specific data that is associated 2737 with the newly created object (for example, a reference to another object). 2738 - If the specified “returnData=’identifier’” 2739 or (if the specified) “returnData=’data’” 2740 then the MUST NOT contain a element.

10407212bb8d0cf1f11a2b881ca263fc19f.doc Page 100 of 158 2741 - Otherwise, if the specified “returnData=’everything’” 2742 or (if the ) omitted the “returnData” attribute, 2743 then the MUST contain a element for each item of capability- 2744 specific data that is associated with the requested object 2745 (and that is specific to a capability that the target supports for the schema entity of which 2746 the requested object is an instance).

2747PSO capability-specific data and IncludeDataForCapability. A MUST 2748include (as sub-elements of each ) any capability-specific data that is 2749associated with the matching object and for which all of the following are true:

2750 The contains a .

2751 The specifies “returnData=’everything’” or (the 2752 ) omits the “returnData” attribute. 2753 The schema for the target declares that the target supports the capability (for the schema entity 2754 of which each matching object is an instance).

2755 The contains an element that specifies 2756 the capability to which the data are specific or the contains no 2757 element.

2758A SHOULD NOT include (as sub-elements of each 2759) any capability-specific data for which any of the above is not true.

2760iterator. A MAY contain at most one element.

2761 If the specifies “status=’success’” and the search response contains 2762 all of the objects that matched the specified , then the MUST 2763 NOT contain an .

2764 If the specifies “status=’success’” and the search response contains 2765 some but not all of the objects that matched the specified , then the 2766 MUST contain exactly one .

2767 If the specifies “status=’success’” and no object matched the 2768 specified , then the MUST NOT contain an .

2769 If the specifies “status=’failure’”, then the 2770 MUST NOT contain an .

2771iterator ID. An MUST have an “ID” attribute.

2772The value of the “ID” attribute uniquely identifies the within the namespace of the 2773provider. The “ID” attribute allows the provider to map each token to the status set of 2774the requestor’s and to any state that records the requestor’s iteration within that status 2775set.

2776The “ID” attribute is (intended to be) opaque to the requestor. A requestor cannot ‘lookup’ an 2777. A requestor cannot specify the “ID” of an in an .

2778Error. If the specifies “status=’failure’”, then the 2779MUST have an “error” attribute that characterizes the failure. See “Error (normative)” for values 2780of this attribute.

10507212bb8d0cf1f11a2b881ca263fc19f.doc Page 101 of 158 2781The section entitled "SearchQueryType Errors (normative)" describes errors specific to a request 2782that contains a . Also see the section entitled “SelectionType Errors (normative)”. 2783In addition, the provider must return an error if any of the following is true:

2784 If the number of objects that matched the that was specified in a 2785 exceeds exceeds any limit on the part of the provider (but does not exceed any value of 2786 “maxSelect” that the requestor specified as part of the ). In this case, the provider's 2787 SHOULD specify "error='insufficientResources'".

27883.5.7.1.3 Examples (non-normative)

2789In the following example, a requestor asks a provider to search for every Person with an email 2790address matching [email protected].

2791The provider returns a . The “status” attribute of the 2792indicates that the provider successfully executed the search operation. [email protected] 2793In the following example, a requestor asks a provider to search for every account that is currently 2794owned by “joebob”. The requestor uses the “returnData” attribute to specify that the provider should 2795return only schema-defined data for each matching object. 2796The provider returns a . The “status” attribute of the 2797indicates that the provider successfully executed the search operation.

10607212bb8d0cf1f11a2b881ca263fc19f.doc Page 102 of 158 27983.5.7.2 iterate

2799The iterate operation obtains the next set of objects from the result set that the provider selected for 2800a search operation. (See the description of the search operation above.) 2801The subset of the Search Capability XSD that is most relevant to the iterate operation follows.

2802An iterateRequest receives an iterateResponse. A requestor supplies the that is 2803output from a as input to an . A provider returns an 2804 in response to each . An has 2805the same structure as a .

2806The will contain at least one element that represents a matching 2807object. If more matching objects are available to return, then the will also 2808contain an . The requestor can use this in another 2809 to retrieve more of the matching objects. 2810Iterate is not batchable. For reasons of scale, neither ‘search’ nor ‘iterate’ should be nested in a 2811batch request. When a search query matches matches more objects than the provider can place 2812directly in the response, the provider must temporarily store the remaining objects. Storing the 2813remaining objects allows allows the requestor to iterate the remaining objects, but also requires the

10707212bb8d0cf1f11a2b881ca263fc19f.doc Page 103 of 158 2814provider to commit resources. See the “Resource Considerations” topic earlier in this Search 2815Capability section. 2816Batch responses also tend to be large. Batch operations are typically asynchronous, so storing the 2817results of asynchronous batch operations imposes on providers a resource burden similar to that of 2818search results. Allowing a requestor to nest a search request or an iterate request within a batch 2819request would aggravate the resource problem, requiring a provider to store more information in 2820larger chunks for a longer amount of time. 2821The iterate operation must be executed synchronously. The provider is already queuing the 2822search set (every object beyond those returned in the first search response), so it is unreasonable 2823for a requestor to ask the provider to queue the results of a request for the next item in the search 2824set. 2825Furthermore, asynchronous iteration would complicate the provider’s maintenance of the search 2826set. Since a provider could never know that the requestor had processed the results of an 2827asynchronous iteration, the provider would not know when to increment its position in the search 2828set. In order to support asynchronous iteration both correctly and generally, a provider would have 2829to maintain a version of every search set for each iteration of that search set.

28303.5.7.2.1 Request (normative)

2831A requestor MUST send an to a provider in order to obtain any additional 2832objects that matched a previous but that the provider has not yet returned to 2833the requestor. (That is, matching objects that were not contained in the response to that 2834 and that have not yet been contained in any response to an 2835 associated with that .)

2836Execution. An MUST NOT specify “executionMode=‘asynchronous’”. 2837A requestor MUST specify “executionMode=‘synchronous’” or (a requestor MUST) omit the 2838“executionMode” attribute of the . See Determining execution type.

2839iterator. An MUST contain exactly one element. A requestor 2840MUST specify the from a as input to an .

28413.5.7.2.2 Response (normative)

2842A provider that receives a from a requestor that the provider trusts must 2843examine the content of the . If the request is valid, the provider MUST return 2844(the XML that represents) the next object in the status set that the represents. 2845Execution. The provider MUST execute the iterate operation synchronously (if the provider 2846executes the iterate operation at all). See the section entitled “Determining execution type”.

2847Response. The provider MUST return to the requestor an .

2848Status. The must contain a “status” attribute that indicates whether the 2849provider successfully returned the next object from the status set that the represents. 2850See “Status (normative)” for values of this attribute. 2851 If the provider successfully returned (the XML that represents) the next object from the status 2852 set that the represents, then the MUST specify 2853 “status=’success’”.

10807212bb8d0cf1f11a2b881ca263fc19f.doc Page 104 of 158 2854 If the provider encountered an error in returning (the XML that represents) the next object from 2855 the status set that the represents, then the MUST specify 2856 “status=’failure’”.

2857Pso. The MAY contain any number of elements.

2858 If the specifies “status=’success’” and at least one object remains 2859 (in the status set that the represents), then the MUST contain 2860 at least one element that contains the (XML representation of the) next matching object.

2861 If the specifies “status=’success’” and no object remains (in the 2862 status set that the represents), then the MUST NOT contain a 2863 element.

2864 If the specifies “status=’failure’”, then the 2865 MUST NOT contain a element.

2866PSO and ReturnData. Each contains the subset of (the XML representation of) a requested 2867object that the “returnData” attribute of the original specified. By default, 2868each contains the entire (XML representation of an) object.

2869 A element MUST contain a element. 2870 The element MUST contain the identifier of the requested object. 2871 See the section entitled “PSO Identifier (normative)”.

2872 A element MAY contain a element. 2873 - If the specified “returnData=’identifier’”, 2874 then the MUST NOT contain a element. 2875 - Otherwise, if the specified “returnData=’data’” 2876 or (if the specified) “returnData=’everything’” 2877 or (if the ) omitted the “returnData” attribute 2878 then the element MUST contain the XML representation of the object. 2879 This XML must be valid according to the schema of the target for the schema entity of 2880 which the newly created object is an instance.

2881 A element MAY contain any number of elements. Each 2882 element contains an item of capability-specific data that is associated 2883 with the newly created object (for example, a reference to another object). 2884 - If the specified “returnData=’identifier’” 2885 or (if the specified) “returnData=’data’” 2886 then the MUST NOT contain a element. 2887 - Otherwise, if the specified “returnData=’everything’” 2888 or (if the ) omitted the “returnData” attribute, 2889 then the MUST contain a element for each item of capability- 2890 specific data that is associated with the requested object 2891 (and that is specific to a capability that the target supports for the schema entity of which 2892 the requested object is an instance).

2893PSO capability-specific data and IncludeDataForCapability. A MUST 2894include (as sub-elements of each ) any capability-specific data that is 2895associated with the matching object and for which all of the following are true:

2896 The contains a .

10907212bb8d0cf1f11a2b881ca263fc19f.doc Page 105 of 158 2897 The original specified “returnData=’everything’” or (the 2898 ) omitted the “returnData” attribute. 2899 The schema for the target declares that the target supports the capability (for the schema entity 2900 of which each matching object is an instance).

2901 The original contained an element that 2902 specified the capability to which the data are specific or the original 2903 contained no element.

2904A SHOULD NOT include (as sub-elements of each 2905) any capability-specific data for which any of the above is not true.

2906iterator. A to an MAY contain at most one 2907 element.

2908 If the specifies “status=’success’” and the search response contains 2909 the last of the objects that matched the that was specified in the original 2910 , then the MUST NOT contain an .

2911 If the specifies “status=’success’” and the provider still has more 2912 matching objects that have not yet been returned to the requestor, then the 2913 MUST contain exactly one .

2914 If the specifies “status=’failure’”, then the 2915 MUST NOT contain an .

2916iterator ID. An MUST have an “ID” attribute.

2917The value of the “ID” attribute uniquely identifies the within the namespace of the 2918provider. The “ID” attribute allows the provider to map each token to the status set of 2919the requestor’s and to any state that records the requestor’s iteration within that status 2920set.

2921The “ID” attribute is (intended to be) opaque to the requestor. A requestor cannot ‘lookup’ an 2922. A requestor cannot specify the “ID” of an in an .

2923Error. If the specifies “status=’failure’”, then the 2924MUST have an “error” attribute that characterizes the failure. See “Error (normative)” for values 2925of this attribute.

2926The MUST specify an appropriate value of “error” if any of the following is 2927true:

2928 If the provider does not recognize the in an as representing 2929 a status set.

2930 If the provider does not recognize the in an as representing 2931 any status set that the provider currently maintains.

2932The MAY specify an appropriate value of “error” if any of the following is 2933true:

2934 If an contains an that is not the most recent version of the 2935 . If the provider has returned to the requestor a more recent that 2936 represents the same search result set, then the provider MAY reject the older . 2937 (A provider that changes the ID—for example, to encode the state of iteration within a search 2938 result set—may be sensitive to this.)

11007212bb8d0cf1f11a2b881ca263fc19f.doc Page 106 of 158 29393.5.7.2.3 Examples (non-normative)

2940In order to illustrate the ‘iterate’ operation, we first need a search operation that returns more than 2941one object. In the following example, a requestor asks a provider to search for every Person with an 2942email address that starts with the letter “j”. 2943The provider returns a . The “status” attribute of the 2944indicates that the provider successfully executed the search operation. The 2945contains two elements that represent the first matching objects. [email protected] [email protected] 2946The requestor asks the provider to return the next matching objects (in the result set for the 2947search). The requestor supplies the from the as input to the 2948. 2949The provider returns an in response to the . The 2950“status” attribute of the indicates that the provider successfully executed 2951the iterate operation. The contains two elements that represent the 2952next matching objects. [email protected]

11107212bb8d0cf1f11a2b881ca263fc19f.doc Page 107 of 158 [email protected] 2953The also contains another element. The “ID” of this 2954 differs from the “ID” of the in the original . The 2955“ID” could remain constant (for each iteration of the status set that the represents) if the 2956provider so chooses, but the “ID” value could change (e.g., if the provider uses ID to encode the 2957state of the status set).

2958To get the final matching object, the requestor again supplies the from the 2959 as input to the . 2960The provider again returns an in response to the . The 2961“status” attribute of the indicates that the provider successfully executed 2962the iterate operation. The contains a element that represents the 2963final matching object. Since all of the matching objects have now been returned to the requestor, 2964this contains no . [email protected] 2965

29663.5.7.3 closeIterator

2967The closeIterator operation tells the provider that the requestor has no further need for the search 2968result that a specific represents. (See the description of the search operation above.)

2969A requestor should send a to the provider when the requestor no 2970longer intends to iterate a search result. (A provider will eventually free an inactive search result 2971--even if the provider never receives a from the requestor-- but this 2972behavior is unspecified. For more information, see the "Resource considerations" topic within the 2973Search Capability section above. 2974The subset of the Search Capability XSD that is most relevant to the iterate operation follows.

11207212bb8d0cf1f11a2b881ca263fc19f.doc Page 108 of 158

2975A closeIteratorRequest receives a closeIteratorResponse. A requestor supplies as input to a 2976 an that was output from a or 2977(that was output from) an . A provider returns a 2978 in response to each . A 2979 has the same structure as an . 2980closeIterator is not batchable. For reasons of scale, none of ‘search’, ‘iterate’ and 'closeIterator' 2981should be nested in a batch request. When a search query matches matches more objects than the 2982provider can place directly in the response, the provider must temporarily store the remaining 2983objects. Storing the remaining objects allows allows the requestor to iterate the remaining objects, 2984but also requires the provider to commit resources. See the “Resource Considerations” topic earlier 2985in this Search Capability section. 2986Batch responses also tend to be large. Batch operations are typically asynchronous, so storing the 2987results of asynchronous batch operations imposes on providers a resource burden similar to that of 2988search results. Allowing a requestor to nest a search request or an iterate request or a closeIterator 2989request within a batch request would aggravate the resource problem, requiring a provider to store 2990more information in larger chunks for a longer amount of time. 2991The closeIterator operation must be executed synchronously. The provider is already queuing 2992the search set (every object beyond those returned in the first search response), so a request to 2993close the iterator (and thus to free the system resources associated with the search set) should be 2994executed as soon as possible. It is unreasonable for a requestor to ask the provider to queue the 2995results of a request to close an iterator (especially since the close iterator response contains little or 2996no information beyond success or failure).

29973.5.7.3.1 Request (normative)

2998A requestor SHOULD send a to a provider when the requestor no 2999longer intends to iterate a search result. (This allows the provider to free any system resources 3000associated with the search result.).

3001Execution. A MUST NOT specify 3002“executionMode=‘asynchronous’”. A requestor MUST specify

11307212bb8d0cf1f11a2b881ca263fc19f.doc Page 109 of 158 3003“executionMode=‘synchronous’” or (a requestor MUST) omit the “executionMode” 3004attribute of the . See Determining execution type.

3005iterator. A MUST contain exactly one element. A 3006requestor MUST specify the from a or (a requestor MUST 3007specify the from an ) as input to a 3008.

30093.5.7.3.2 Response (normative)

3010A provider that receives a from a requestor that the provider trusts 3011must examine the content of the . If the request is valid, the provider 3012MUST release the search set that the represents. Any subsequent request to iterate 3013that search result MUST fail. 3014Execution. The provider MUST execute the iterate operation synchronously (if the provider 3015executes the iterate operation at all). See the section entitled “Determining execution type”.

3016Response. The provider MUST return to the requestor a .

3017Status. The must contain a “status” attribute that indicates 3018whether the provider successfully released the search result set that the represents. 3019See “Status (normative)” for values of this attribute.

3020 If the provider successfully released the search result that the represents, then 3021 the MUST specify “status=’success’”.

3022 If the provider encountered an error in releasing the search result that the 3023 represents, then the MUST specify “status=’failure’”.

3024Error. If the specifies “status=’failure’”, then the 3025 MUST have an “error” attribute that characterizes the failure. 3026See “Error (normative)” for values of this attribute.

3027The MUST specify an appropriate value of “error” if any of the 3028following is true:

3029 If the provider does not recognize the in a as 3030 representing a search result.

3031 If the provider does not recognize the in a as 3032 representing any search result that the provider currently maintains.

3033The MAY specify an appropriate value of “error” if any of the following is 3034true:

3035 If a contains an that is not the most recent version 3036 of the . If the provider has returned to the requestor a more recent 3037 that represents the same search result set, then the provider MAY reject the older 3038 . 3039 (A provider that changes the ID—for example, to encode the state of iteration within a search 3040 result set—may be sensitive to this.)

11407212bb8d0cf1f11a2b881ca263fc19f.doc Page 110 of 158 30413.5.7.3.3 Examples (non-normative)

3042In order to illustrate the ‘closeIterator’ operation, we first need a search operation that returns more 3043than one object. In the following example, a requestor asks a provider to search for every Person 3044with an email address that starts with the letter “j”.

3045The provider returns a . The “status” attribute of the 3046indicates that the provider successfully executed the search operation. The 3047contains two elements that represent the first matching objects. [email protected] [email protected] 3048The requestor decides that the two objects in the initial will suffice, and does 3049not intend to retrieve any more matching objects (in the result set for the search). The requestor 3050supplies the from the as input to the 3051. 3052The provider returns a in response to the 3053. The “status” attribute of the 3054indicates that the provider successfully released the search result.

11507212bb8d0cf1f11a2b881ca263fc19f.doc Page 111 of 158 3055

30563.5.8 Suspend Capability

3057The Suspend Capability is defined in a schema associated with the following XML namespace: 3058urn:oasis:names:tc:SPML:2:0:suspend. This document includes the Suspend Capability 3059XSD as Appendix H. 3060The Suspend Capability defines three operations: ‘suspend’, ‘resume’ and ‘active’. 3061 The ‘suspend’ operation disables an object (immediately or on a specified date). 3062 The ‘resume’ operation re-enables an object (immediately or on a specified date). 3063 The ‘active’ operation tests whether an object is currently suspended. 3064The ‘suspend’ operation disables an object persistently (rather than transiently). The suspend 3065operation is intended to revoke the privileges of an account, for example, while the authorized user 3066of the account is on vacation. 3067The ‘resume’ operation re-enables an object persistently. One might use the resume operation to 3068restore privileges for an account, for example, when the authorized user of the account returns from 3069vacation. 3070A provider that supports the ‘suspend’, ‘resume’ and ‘active’ operations for a target SHOULD 3071declare that the target supports the Suspend Capability. A provider that does not support all of 3072‘suspend’, ‘resume’ and ‘active’ MUST NOT declare that the target supports the Suspend 3073Capability. 3074NOTE: Both the suspend and resume operations are idempotent. Are requestor should be able to 3075suspend (or to resume) the same object multiple times without error.

3076Search. A requestor can search for objects based on enabled state using the query 3077clause. The {IsActiveType} extends {QueryClauseType}, which indicates that an instance 3078of {IsActiveType} can be used to select objects. An clause matches an object if 3079and only if the object is currently enabled. In order to select disabled objects, a requestor would 3080combine this clause with the logical operator . See the section entitled “Selection”.

30813.5.8.1 suspend

3082The suspend operation enables a requestor to disable an object. 3083The subset of the Suspend Capability XSD that is most relevant to the suspend operation follows.

11607212bb8d0cf1f11a2b881ca263fc19f.doc Page 112 of 158

30843.5.8.1.1 Request (normative)

3085A requestor MUST send a to a provider in order to (ask the provider to) 3086disable an existing object. 3087Execution. A requestor MAY specify a type of execution for a ‘suspend’ operation. See 3088Determining execution type.

3089psoID. A MUST contain exactly one element. A element 3090MUST identify an object that exists on a target that is exposed by the provider. See the section 3091entitled "PSO Identifier (normative)".

3092EffectiveDate. A MAY specify an “effectiveDate”. Any 3093“effectiveDate” value MUST be expressed in UTC form, with no time zone component. 3094A requestor or a provider SHOULD NOT rely on time resolution finer than milliseconds. 3095A requestor MUST NOT generate time instants that specify leap seconds.

30963.5.8.1.2 Response (normative)

3097A provider that receives a from a requestor that the provider trusts MUST 3098examine the content of the . If the request is valid and if the specified object 3099exists, then the provider MUST disable the object that is specified by the .

3100If the specifies an “effectiveDate”, the provider MUST enable the 3101specified object as of that date.

3102 If the “effectiveDate” of the is in the past, then 3103 the provider MUST do one of the following: 3104 - The provider MAY disable the specified object immediately. 3105 - The provider MAY return an error. (The provider’s response SHOULD indicate that the 3106 request failed because the effective date is past.)

3107 If the “effectiveDate” of the is in the future, then 3108 - The provider MUST NOT disable the specified object until that future date and time. 3109 - The provider MUST disable the specified object at that future date and time 3110 (unless a subsequent request countermands this request). 3111Execution. If an does not have an execution attribute, the provider MUST 3112choose a type of execution for the requested operation. See the section entitled “Determining 3113execution type”.

3114Response. The provider must return to the requestor a . The 3115 must have a “status” attribute that indicates whether the provider 3116successfully disabled the specified object. See “Status (normative)” for values of this attribute.

3117Error. If the provider cannot create the requested object, the must contain 3118an error attribute that characterizes the failure. See “Error (normative)” for values of this attribute. 3119The provider MUST return an error if any of the following is true:

3120 The contains a for an object that does not exist.

3121 The specifies an “effectiveDate” that is not valid.

11707212bb8d0cf1f11a2b881ca263fc19f.doc Page 113 of 158 3122The provider MAY return an error if any of the following is true:

3123 The specifies an “effectiveDate” that is in the past. 3124The provider MUST NOT return an error when (the operation would otherwise succeed and) the 3125object is already disabled. In this case, the response should specify “status=’success’”.

31263.5.8.1.3 Examples (non-normative)

3127In the following example, a requestor asks a provider to suspend an existing Person object. 3128The provider returns an element. The “status” attribute of the 3129 element indicates that the provider successfully disabled the specified 3130object. 3131In the following example, a requestor asks a provider to suspend an existing account. 3132The provider returns a . The “status” attribute of the 3133 indicates that the provider successfully disabled the specified account.

31343.5.8.2 resume

3135The resume operation enables a requestor to re-enable an object that has been suspended. (See 3136the description of the suspend operation above.) 3137The subset of the Suspend Capability XSD that is most relevant to the resume operation follows.

31383.5.8.2.1 Request (normative)

3139A requestor MUST send a to a provider in order to (ask the provider to) re- 3140enable an existing object.

11807212bb8d0cf1f11a2b881ca263fc19f.doc Page 114 of 158 3141Execution. A requestor MAY specify a type of execution for a ‘resume’ operation. See Determining 3142execution type.

3143psoID. A MUST contain exactly one element. A element 3144MUST identify an object that exists on a target (that is supported by the provider). See the section 3145entitled "PSO Identifier (normative)".

3146EffectiveDate. A MAY specify an “effectiveDate”. Any 3147“effectiveDate” value MUST be expressed in UTC form, with no time zone component. 3148A requestor or a provider SHOULD NOT rely on time resolution finer than milliseconds. 3149A requestor MUST NOT generate time instants that specify leap seconds.

31503.5.8.2.2 Response (normative)

3151A provider that receives a from a requestor that the provider trusts MUST 3152examine the content of the . If the request is valid and if the specified object 3153exists, then the provider MUST enable the object that is specified by the .

3154If the specifies an “effectiveDate”, the provider MUST enable the 3155specified object as of that date.

3156 If the “effectiveDate” of the is in the past, then 3157 the provider MUST do one of the following: 3158 - The provider MAY enable the specified object immediately. 3159 - The provider MAY return an error. (The provider’s response SHOULD indicate that the 3160 request failed because the effective date is past.)

3161 If the “effectiveDate” of the is in the future, then 3162 - The provider MUST NOT enable the specified object until that future date and time. 3163 - The provider MUST enable the specified object at that future date and time 3164 (unless a subsequent request countermands this request). 3165Execution. If an does not have an execution attribute, the provider MUST 3166choose a type of execution for the requested operation. See the section entitled “Determining 3167execution type”.

3168Response. The provider must return to the requestor a . The 3169 must have a “status” attribute that indicates whether the provider 3170successfully enabled the specified object. See “Status (normative)” for values of this attribute.

3171Error. If the provider cannot enable the requested object, the must contain 3172an error attribute that characterizes the failure. See “Error (normative)” for values of this attribute. 3173The provider MUST return an error if any of the following is true:

3174 The contains a for an object that does not exist.

3175 The specifies an “effectiveDate” that is not valid. 3176The provider MAY return an error if any of the following is true:

3177 The specifies an “effectiveDate” that is in the past. 3178The provider MUST NOT return an error when (the operation would otherwise succeed and) the 3179object is already enabled. In this case, the response should specify “status=’success’”.

11907212bb8d0cf1f11a2b881ca263fc19f.doc Page 115 of 158 31803.5.8.2.3 Examples (non-normative)

3181In the following example, a requestor asks a provider to resume an existing Person object. 3182The provider returns a element. The “status” attribute of the 3183 element indicates that the provider successfully disabled the specified object. 3184In the following example, a requestor asks a provider to resume an existing account. 3185The provider returns a . The “status” attribute of the 3186 indicates that the provider successfully enabled the specified account.

31873.5.8.3 active

3188The active operation enables a requestor to determine whether a specified object has been 3189suspended. (See the description of the suspend operation above.) 3190The subset of the Suspend Capability XSD that is most relevant to the active operation follows.

31913.5.8.3.1 Request (normative)

3192A requestor MUST send an to a provider in order to (ask the provider to) 3193determine whether the specified object is enabled (active) or disabled.

12007212bb8d0cf1f11a2b881ca263fc19f.doc Page 116 of 158 3194Execution. A requestor MAY specify a type of execution for an active operation. See Determining 3195execution type.

3196psoID. A MUST contain exactly one element. A element 3197MUST identify an object that exists on a target that is exposed by the provider. See the section 3198entitled "PSO Identifier (normative)".

31993.5.8.3.2 Response (normative)

3200A provider that receives a from a requestor that the provider trusts MUST 3201examine the content of the . If the request is valid and if the specified object 3202exists, then the provider MUST disable the object that is specified by the .

3203Execution. If an does not have an execution attribute, the provider MUST 3204choose a type of execution for the requested operation. See the section entitled “Determining 3205execution type”.

3206Response. The provider must return to the requestor an . The 3207 must have a “status” attribute that indicates whether the provider 3208successfully determined whether the specified object is enabled (i.e. active). See “Status 3209(normative)” for values of this attribute.

3210active. An MAY have an “active” attribute that indicates whether the 3211specified object is suspended. An that specifies “status=’success’” 3212MUST have an “active” attribute.

3213 If the specified object is suspended, the MUST specify 3214 “active=’false’”.

3215 If the specified object is not suspended, the MUST specify 3216 “active=’false’”. 3217Error. If the provider cannot determine whether the requested object is suspended, the 3218 must contain an “error” attribute that characterizes the failure. See “Error 3219(normative)” for values of this attribute. 3220The provider MUST return an error if any of the following is true:

3221 The contains a that specifies an object that does not exist.

32223.5.8.3.3 Examples (non-normative)

3223In the following example, a requestor asks a provider whether a Person object is active. 3224The provider returns an element. The “status” attribute of the 3225 element indicates that the provider successfully completed the requested 3226operation. The “active” attribute of the indicates that the specified object is 3227active. 3228In the following example, a requestor asks a provider whether an account is active.

12107212bb8d0cf1f11a2b881ca263fc19f.doc Page 117 of 158 3229The provider returns an . The “status” attribute of the 3230 indicates that the provider successfully completed the requested operation. 3231The “active” attribute of the indicates that the specified object is active.

12207212bb8d0cf1f11a2b881ca263fc19f.doc Page 118 of 158 32323.6 Custom Capabilities 3233The features of SPMLv2 that allow the PSTC to define optional operations as part of standard 3234capabilities are open mechanisms that will work for anyone. An individual provider (or any third 3235party) can define a custom capability that integrates with SPMLv2. Whoever controls the 3236namespace of the capability controls the extent to which it can be shared. Each provider 3237determines which capabilities are supported for which types of objects on which types of targets. 3238The SPMLv2 capability mechanism is extensible. Any party may define additional capabilities. A 3239provider declares its support for a custom capability in exactly the same way that it declares support 3240for a standard capability: as a target element. 3241The standard capabilities that SPMLv2 defines will not address all needs. Contributors may define 3242additional custom capabilities. 3243Since the schema for each capability is defined in a separate namespace, a custom capability will 3244not ordinarily conflict with a standard capability that is defined as part of SPMLv2, nor will a custom 3245capability ordinarily conflict with another custom capability. In order for a custom capability B to 3246conflict with another capability A, capability B would have to import the namespace of capability A 3247and redeclare a schema element from capability A. Such a conflict is clearly intentional and a 3248provider can easily avoid such a conflict by not declaring support for capability B. 3249Also see the section below entitled “Conformance”.

12307212bb8d0cf1f11a2b881ca263fc19f.doc Page 119 of 158 124

32504 Conformance (normative)

32514.1 Core operations and schema are mandatory

3252A conformant provider MUST support the elements, attributes, and types defined in the SPMLv2 3253Core XSD. This includes all the core operations and protocol behavior.

3254Schema syntax for the SPMLv2 core operations is defined in a schema that is associated with the 3255following XML namespace: urn:oasis:names:tc:SPML:2:0. This document includes the Core 3256XSD as Appendix A.

32574.2 Standard capabilities are optional

3258A conformant provider SHOULD support the schema and operations defined by each standard 3259capability of SPMLv2. 3260A conformant provider MUST NOT expose an operation that competes with (i.e., whose functions 3261overlap those of) an operation defined by a standard capability of SPMLv2 3262UNLESS all of the following are true: 3263 The provider MUST define the competing operation in a custom capability. 3264 Every target (and every schema entity on a target) that supports the provider’s custom 3265 capability MUST also support the standard capability.

32664.3 Custom capabilities

3267A conformant provider MUST use the custom capability mechanism of SPMLv2 to expose any 3268operation beyond those specified by the core and standard capabilities of SPMLv2. 3269A conformant provider MAY support any custom capability that conforms to SPMLv2. 3270Custom capabilities must conform. Any operation that a custom capability defines MUST be 3271defined as a request-response pair such that all of the following are true:

3272 The request type (directly or indirectly) extends {RequestType}

3273 The response type is {ResponseType} or (the response type directly or indirectly) extends 3274 {ResponseType}. 3275Custom capabilities should not conflict. Since each custom capability is defined in its own 3276namespace, an element or attribute in the XML schema that is associated with a custom capability 3277SHOULD NOT not conflict with (i.e., SHOULD NOT redefine and SHOULD NOT otherwise change 3278the definition of) any element or attribute in any other namespace: 3279 A custom capability MUST NOT conflict with the Core XSD of SPMLv2. 3280 A custom capability MUST NOT conflict with any standard capability of SPMLv2. 3281 A custom capability SHOULD NOT conflict with another custom capability.

12507212bb8d0cf1f11a2b881ca263fc19f.doc Page 120 of 158 126

32825 Security and privacy considerations

3283This section identifies scenarios that compromise security and privacy. Scenarios such as these 3284should be considered when implementing an SPML-based system. This section is purely 3285informative. Each implementer must evaluate the risks and select appropriate safeguards.

32865.1 Threat model

3287We assume here that an adversary has access to the communication channel between the SPML 3288requestor and provider and is able to interpret, insert, delete and modify messages or parts of 3289messages.

32905.1.1 Unauthorized disclosure

3291SPML does not specify any inherent mechanisms for confidentiality of the messages exchanged 3292between actors. Therefore, an adversary could observe the messages in transit. Disclosure of the 3293information contained in SPML messages may constitute a violation of certain security policies. 3294Disclosure of provisioning data may have significant repercussions. In the commercial sector, the 3295consequences of unauthorized disclosure of personal data may range from public embarrassment 3296of the corporation to imprisonment of and large fines for its officers. Statutory penalties are 3297especially high in the case of medical or financial data. 3298Confidentiality mechanisms (see below) address unauthorized disclosure.

32995.1.2 Message Replay

3300A message replay attack is one in which an adversary records and replays legitimate messages 3301between SPML actors. This attack may lead to denial of service, impersonation, or simply out-of- 3302date information. 3303An implementer must use message “freshness” mechanisms in order to prevent replay attacks. 3304Note that message encryption does not mitigate a replay attack since an attacker merely replays 3305(and does not need to understand) the message.

33065.1.2.1 Message insertion

3307A message insertion attack is one in which an adversary inserts messages in the sequence of 3308messages between SPML actors. 3309The solution to a message insertion attack is to use mutual authentication and a message 3310sequence integrity mechanism between the actors. It should be noted that just using SSL mutual 3311authentication is not sufficient. SSL mutual authentication proves only that the other party is the one 3312identified by the subject of the X.509 certificate. In order to be effective, it is necessary to confirm 3313that the certificate subject is authorized to send the message.

33145.1.2.2 Message deletion

3315A message deletion attack is one in which the adversary deletes messages in the sequence of 3316messages between SPML actors. Message deletion may lead to denial of service. However, a

12707212bb8d0cf1f11a2b881ca263fc19f.doc Page 121 of 158 3317properly designed SPML system should not trigger false provisioning on as the status of a message 3318deletion attack. 3319The solution to a message deletion attack is to use a message integrity mechanism between the 3320actors.

33215.1.2.3 Message modification 3322If an adversary can intercept a message and change its contents, then the adversary may be able 3323to alter a provisioning request. Message integrity mechanisms can prevent a message modification 3324attack from succeeding.

33255.2 Safeguards

33265.2.1 Authentication

3327Authentication provides the means for one party in a transaction to determine the identity of the 3328other party in the transaction. Authentication may be unilateral (in one direction) or it may be 3329bilateral (on both sides). 3330Given the sensitive nature of many provisioning requests and systems it is important for a 3331requestor (client) to authenticate the provider (server). Otherwise, there is a risk that an adversary 3332could act as a provider, leading to a possible security violation. 3333It is equally important for a provider to authenticate the requestor, to assess the level of trust 3334between them and to determine whether the requestor is authorized to request each operation. 3335Many different techniques may be used to provide authentication, such as co-located code, a 3336private network, a VPN or digital signatures. Authentication may also be performed as part of the 3337communication protocol that is used to exchange the requests. When authentication is performed 3338as part of the protocol, authentication may be performed for each session or for each message.

33395.2.2 Confidentiality

3340Confidentiality mechanisms ensure that only the desired recipients can read the contents of a 3341message. The primary concern is confidentiality during transmission.

33425.2.2.1 Communication confidentiality

3343In some environments it is deemed good practice to treat all data within a provisioning domain as 3344confidential. In other environments certain parts of the service schema and required attributes may 3345be published. Regardless of the approach, the security of the provisioning system as a whole 3346should not depend in any way on the secrecy of the service, on the secrecy of the service’s 3347provider, nor on the secrecy of the service’s request data schema. 3348Any security concern or requirement related to transmitting or exchanging SPML documents lies 3349outside the scope of the SPML standard. Ensuring the integrity and confidentiality of provisioning 3350requests is generally important, but the implementer must determine which mechanisms are 3351appropriate for each implementation environment. 3352A confidentiality mechanism, such as SSL, can provide communications confidentiality. However, a 3353point-to-point scheme like SSL may lead to other vulnerabilities if one of the end-points is 3354compromised.

12807212bb8d0cf1f11a2b881ca263fc19f.doc Page 122 of 158 33555.2.2.2 Trust model

3356Discussions of authentication, integrity and confidentiality mechanisms necessarily assume an 3357underlying trust model: how can one actor come to believe that a given key is uniquely associated 3358with a specific, identified actor so that the key can be used to encrypt data for that actor or verify 3359signatures (or other integrity structures) from that actor? Many different types of trust model exist, 3360including strict hierarchies, distributed authorities, the Web, the bridge and so on.

33615.2.2.3 Privacy

3362It is important to be aware that any transactions that occur in an SPML model system may contain 3363private and secure information about the actors. Selection and use of privacy mechanisms 3364appropriate to a given environment are outside the scope of this specification. The decisions 3365regarding whether, how and when to deploy such mechanisms is left to the implementers 3366associated with the environment.

12907212bb8d0cf1f11a2b881ca263fc19f.doc Page 123 of 158 130

3367Appendix A. Core XSD

13107212bb8d0cf1f11a2b881ca263fc19f.doc Page 124 of 158 use="optional"/>

13207212bb8d0cf1f11a2b881ca263fc19f.doc Page 125 of 158

13307212bb8d0cf1f11a2b881ca263fc19f.doc Page 126 of 158

13407212bb8d0cf1f11a2b881ca263fc19f.doc Page 127 of 158

13507212bb8d0cf1f11a2b881ca263fc19f.doc Page 128 of 158

13607212bb8d0cf1f11a2b881ca263fc19f.doc Page 129 of 158

3368

13707212bb8d0cf1f11a2b881ca263fc19f.doc Page 130 of 158 3369Appendix B. Async Capability XSD

13807212bb8d0cf1f11a2b881ca263fc19f.doc Page 131 of 158

3370

13907212bb8d0cf1f11a2b881ca263fc19f.doc Page 132 of 158 3371Appendix C. Batch Capability XSD

Elements that extend spml:RequestType

14007212bb8d0cf1f11a2b881ca263fc19f.doc Page 133 of 158

Elements that extend spml:ResponseType

3372

14107212bb8d0cf1f11a2b881ca263fc19f.doc Page 134 of 158 3373Appendix D. Bulk Capability XSD

14207212bb8d0cf1f11a2b881ca263fc19f.doc Page 135 of 158

3374

14307212bb8d0cf1f11a2b881ca263fc19f.doc Page 136 of 158 3375Appendix E. Password Capability XSD

14407212bb8d0cf1f11a2b881ca263fc19f.doc Page 137 of 158

3376

14507212bb8d0cf1f11a2b881ca263fc19f.doc Page 138 of 158 3377Appendix F. Reference Capability XSD

14607212bb8d0cf1f11a2b881ca263fc19f.doc Page 139 of 158

3378

14707212bb8d0cf1f11a2b881ca263fc19f.doc Page 140 of 158 3379Appendix G. Search Capability XSD

14807212bb8d0cf1f11a2b881ca263fc19f.doc Page 141 of 158

14907212bb8d0cf1f11a2b881ca263fc19f.doc Page 142 of 158

15007212bb8d0cf1f11a2b881ca263fc19f.doc Page 143 of 158 3380Appendix H. Suspend Capability XSD

15107212bb8d0cf1f11a2b881ca263fc19f.doc Page 144 of 158

3381

15207212bb8d0cf1f11a2b881ca263fc19f.doc Page 145 of 158 3382Appendix I. Document References 3383 [ARCHIVE-1] OASIS Provisioning Services Technical Committee, email archive, 3384 http://www.oasis- 3385 open.org/apps/org/workgroup/provision/email/archives/index. 3386 html, OASIS PS-TC

3388 [DS] IETF/W3C, W3C XML Signatures, http://www.w3.org/Signature/, 3389 W3C/IETF

3391 [DSML] OASIS Directory Services Markup TC, DSML V2.0 Specification, 3392 http://www.oasis- 3393 open.org/apps/org/workgroup/dsml/documents.php, OASIS 3394 DS-TC

3396 [GLOSSARY] OASIS Provisioning Services TC, Glossary of Terms, 3397 http://www.oasis- 3398 open.org/apps/org/workgroup/provision/download.php/???, 3399 OASIS PS-TC

3401 [RFC2119] S. Bradner., Key words for use in RFCs to Indicate Requirement 3402 Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF

3404 [SAML] OASIS Security Services TC, XMLTitle, http://www.oasis- 3405 open.org/apps/org/workgroup/sstc/documents.php, OASIS 3406 SS-TC

3408 [SPML-Bind]] OASIS Provisioning Services TC, SPML V1.0 Protocol Bindings, 3409 http://www.oasis- 3410 open.org/apps/org/workgroup/provision/download.php/1816/d 3411 raft-pstc-bindings-03.doc, OASIS PS-TC

3413 [SPML-REQ] OASIS Provisioning Services Technical Committee, Requirements, 3414 http://www.oasis- 3415 open.org/apps/org/workgroup/provision/download.php/2277/d 3416 raft-pstc-requirements-01.doc, OASIS PS-TC

3418 [SPML-UC] OASIS Provisioning Services Technical Committee, SPML V1.0 3419 Use Cases, http://www.oasis- 3420 open.org/apps/org/workgroup/provision/download.php/988/drf 3421 at-spml-use-cases-05.doc, OASIS PS-TC

3423 [SPMLv2-Profile-DSML] OASIS Provisioning Services Technical Committee, SPMLv2 3424 DSMLv2 Profile, OASIS PS-TC

3426 [SPMLv2-Profile-XSD ] OASIS Provisioning Services Technical Committee, SPML V2 XSD 3427 Profile, OASIS PS-TC

3429 [SPMLv2-REQ] OASIS Provisioning Services Technical Committee, Requirements, 3430 , OASIS PS-TC

15307212bb8d0cf1f11a2b881ca263fc19f.doc Page 146 of 158 3432 [SPMLv2-ASYNC] OASIS Provisioning Services Technical Committee, XML Schema 3433 Definitions for Async Capability of SPMLv2, OASIS PS-TC

3435 [SPMLv2-BATCH] OASIS Provisioning Services Technical Committee, XML Schema 3436 Definitions for Batch Capability of SPMLv2, OASIS PS-TC

3438 [SPMLv2-BULK] OASIS Provisioning Services Technical Committee, XML Schema 3439 Definitions for Bulk Capability of SPMLv2, OASIS PS-TC

3441 [SPMLv2-CORE] OASIS Provisioning Services Technical Committee, XML Schema 3442 Definitions for Core Operations of SPMLv2, , OASIS PS-TC

3444 [SPMLv2-PASS] OASIS Provisioning Services Technical Committee, XML Schema 3445 Definitions for Password Capability of SPMLv2, , OASIS PS-TC

3447 [SPMLv2-REF] OASIS Provisioning Services Technical Committee, XML Schema 3448 Definitions for Reference Capability of SPMLv2, , OASIS PS-TC

3450 [SPMLv2-SEARCH] OASIS Provisioning Services Technical Committee, XML Schema 3451 Definitions for Search Capability of SPMLv2, , OASIS PS-TC

3453 [SPMLv2-UC] OASIS Provisioning Services Technical Committee., SPML V2.0 3454 Use Cases, , OASIS PS-TC

3456 [XSD] W3C Schema WG ., W3C XML Schema, 3457 http://www.w3.org/TR/xmlschema-1/ W3C

3459 3460

15407212bb8d0cf1f11a2b881ca263fc19f.doc Page 147 of 158 155

3461Appendix J. Acknowledgments

3462The following individuals were voting members of the Provisioning Services committee at the time 3463that this version of the specification was issued: 3464List Members Here: 3465 3466

15607212bb8d0cf1f11a2b881ca263fc19f.doc Page 148 of 158 157

3468Appendix K. Notices

3469OASIS takes no position regarding the validity or scope of any intellectual property or other rights 3470that might be claimed to pertain to the implementation or use of the technology described in this 3471document or the extent to which any license under such rights might or might not be available; 3472neither does it represent that it has made any effort to identify any such rights. Information on 3473OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS 3474website. Copies of claims of rights made available for publication and any assurances of licenses to 3475be made available, or the result of an attempt made to obtain a general license or permission for 3476the use of such proprietary rights by implementors or users of this specification, can be obtained 3477from the OASIS Executive Director. 3478OASIS invites any interested party to bring to its attention any copyrights, patents or patent 3479applications, or other proprietary rights which may cover technology that may be required to 3480implement this specification. Please address the information to the OASIS Executive Director. 3481Copyright © OASIS Open 2004. All Rights Reserved. 3482This document and translations of it may be copied and furnished to others, and derivative works 3483that comment on or otherwise explain it or assist in its implementation may be prepared, copied, 3484published and distributed, in whole or in part, without restriction of any kind, provided that the above 3485copyright notice and this paragraph are included on all such copies and derivative works. However, 3486this document itself may not be modified in any way, such as by removing the copyright notice or 3487references to OASIS, except as needed for the purpose of developing OASIS specifications, in 3488which case the procedures for copyrights defined in the OASIS Intellectual Property Rights 3489document must be followed, or as required to translate it into languages other than English. 3490The limited permissions granted above are perpetual and will not be revoked by OASIS or its 3491successors or assigns. 3492This document and the information contained herein is provided on an “AS IS” basis and OASIS 3493DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO 3494ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY 3495RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 3496PARTICULAR PURPOSE

15807212bb8d0cf1f11a2b881ca263fc19f.doc Page 149 of 158 159

3497Appendix L. Revision history

16007212bb8d0cf1f11a2b881ca263fc19f.doc Page 150 of 158 Rev Date By What Whom D- 20041001 Editor 0.1 Rough Draft. 01 D- 20041019 Editor Review Schema section. 01 Minor corrections to draft XSD. D- 20041026 Editor Define a Batch capability. 01 (Batch operation is no longer part of the core) D- 20041026 Editor Rework asynchronous execution. 01 1) By default, execution type is unspecified. 2) Requestor can specify asynchronous execution for ANY operation except cancel and status. Provider must execute as specified (or fail the request if unable to do so). 3) Provider can convert a request (for any operation except cancel and status) that does not specify synchronous execution to asynchronous execution (e.g., if workflow makes this necessary) 4) Provider returns requestID for any operation that the provider executes asynchronously. 5) Define Async Capability (so provider can indicate whether it supports asynchronous execution). May also contain cancel and status operations. D- 20041029 Editor Retention limit for results of async operations 01 does not rise to the level of specification. D- 20041102 Editor Review Introduction and Concepts sections. 01 1) Do not use Java to explain Capability 2) Target schema cannot contain DSML (because DSML deprecates schema); we mean “DSML binding for SPMLv2”. 3) Make clear that a target is not a provider (but is instead a container of objects that a provider manages) D- 20041115 Gerry Review Protocol section. 01 Woods 1) Remove language stating that the requestID value SHOULD be globally unique so that the value will not conflict with any other requestID value that the requestor may receive from any provider.” 2) Describe single-operation requests as ‘individual’ requests rather than ‘singleton’ requests. 3) PSO-IDs are required only to be unique within provider (rather than

16107212bb8d0cf1f11a2b881ca263fc19f.doc Page 151 of 158 globally unique). 4) ListTargets MUST be synchronous (previously said SHOULD). 5) Removed repetition of “open content” in listTargets/schema section. 6) Cleaned up listTargets example: - Remove XML Processing Instructions - Capability identifiers are namespaces - Status code values are no longer fully qualified D- 20041116 Editor Distributed draft Protocol/Async Capability section. 01 D- 20041118 Editor Distributed draft Protocol/Batch Capability section. 01 D- 20041129 Editor Distributed draft Protocol/Bulk, Password, Reference, Search and 01 Suspend Capability sections. D- 20041201 Editor Removed Schema section. Since each protocol section includes 01 relevant schema snippets (and normatively describes both request and response for every operation), schema section was redundant (and not worth 40-60 pages). D- 20041205 Editor Pasted in Draft 9 Schema snippets. Moved each complete schema 02 section into an appendix. Indicated pending and proposed XSD changes with red font and sometimes strikethrough. Renamed capabilityParameter to capabilityData. Renamed ObjectClassRefType to SchemaEntityRefType. Added sub-element to psoType. Modify operation may now return entire . D- 20041207 Editor Pasted in Draft 10 Schema snippets. Updated text to reflect issues 03 resolved in Draft 10. Abstract: Specification no longer defines schema. Audience: Pointed each audience to one section. Restored mention of appendix. Concepts: Merge Target subsection into Target subsection of DomainModel. Domain Model: Note that Gerry will send UML to replace ERD. Rename RA to requestor, PSP to provider, PST to target. Remove Terms subsection since it is no longer needed. Protocol: removed subsection regarding Profiles. Profiles now described only in Concepts. Renamed “DSML Schema” to “SPML1.0 Schema” and “DSML Profile” to “SPML1.0 Profile”. D- 20041209 Editor Protocol: added Conversational Flow section within 03 Request/Response Model. Recommended requestID. Determining execution type: renamed to “Determining execution

16207212bb8d0cf1f11a2b881ca263fc19f.doc Page 152 of 158 mode”. Added bullet-pointed list of the four possibilities. SelectionType: Added subsection to describe “SelectionType processing in a Response (normative).” Delete: Say that Provider MUST ignore capability-specific data. D- 20041210 Editor Pasted in Draft 11 XSD files into Appendices. 03 Updated snippets for Protocol Request/Response model and Synchronous and Asynchronous Operations. D- 20041214 Editor ListTargets: pasted in Draft 11 XSD snippets. 03 Added discussion of SchemaEntityRefType#isContainer. Added discussion of SchemaType#ref element Added discussion of capabilities element wrapping capability. Add: pasted in Draft 11 XSD snippets. Added discussion of AddRequestType#returns. Renamed “parentId” to “containerID” (per Draft 11) AddResponseType#pso content depends on “returns” D- 20041216 Editor Lookup: pasted in Draft 11 XSD snippets. 03 Added discussion of LookupRequestType#returns. LookupResponseType#pso content depends on “returns” Lookup examples illustrate “returns” attribute. Moved Conformance before Security and Privacy Considerations. D- 20050112 Editor Pasted in remaining Draft 11 XSD snippets. 03 Discussed “returns” attribute and its effect on content for: Modify, Search, Iterate.

Discussed for Search.

Discussed “recursive” attribute for Delete. D- 20050215 Editor Updated to Draft 13 XSD. 03 Updated OASIS Notices for 2005.

Explained (in the non-normative section that introduces the Async Capability) why the cancel and status operations must be synchronous.

Explained (in the non-normative section that introduces the Search Capability) why the iterate operation must be synchronous.

Specified that neither suspend nor resume should return an error when the object is already in the desired state. Explained (in the non- normative section that introduces the Suspend Capability) that the suspend and resume operations are idempotent. D- 20050225 Editor Removed Glossary appendix. Add Reference to [GLOSSARY] as a 03 separate document.

Removed Requirements appendix. Add Reference to [SPMLv2-REQ] as a separate document.

16307212bb8d0cf1f11a2b881ca263fc19f.doc Page 153 of 158 D- 20050308 Editor Removed Editor’s note in 3.4.1.2.2. Per agreement on #40 in 04 draft_13_xsd_issues.txt, schema declares valid containers. Invalid content is an exception.

Documented “Status and Error Codes” as a general feature of the protocol. (This replaces references to normative Schema sections.)

D- 20050325 Editor Explained (in the non-normative section that introduces each) why the 04 listTargets, batch, search, iterate, cancel and status operations are not batchable. Stated (in the normative section that describes the batch request) that these operations must not be nested within a batch request.

D- 20050326 Editor Updated schema appendices, schema snippets and examples to XSD 04 version 15. D- 20050404 Editor Updated names of XSD Profile and DSMLv2 Profile documents. 05 Renamed “SPML1.0 Profile” (back) to “DSMLv2 Profile”. Clarified that content of schema element takes precedence over any reference to a schema URN or URL. Removed from the Concepts section most of the language that referred to SPML 1.0. Removed statement that SPMLv2 continues to supports SPML1.0 as a profile. Now say only that DSMLv2 profile supports a similar schema model. Added normative sub-section specific to Status (and normative subsection specific to Error) within “Status and Error codes”. Reworded “Conversational flow” section to avoid the word “blocking”. Removed some language (including the introductory paragraph) that suggested order that does not exist over a connectionless protocol.

Mentioned that modify can change PSO-ID in non-normative section that introduces the modify operation. Discussed adding and modifying a reference in modify Examples.

D- 20050404 Editor Use ‘http://www.w3.org/TR/xpath20’ as namespaceURI for Xpath. 06 Illustrate targetID as an attribute (with additions and strikethroughs). Removed namespace qualifier from status values (e.g., “success”). Correct miscellaneous errors in examples (noted by Rami Elron). Assume top-level elements bulkModifyResponse and bulkDeleteResponse of type spml:ResponseType. Assume top-level element iterateResponse of type

16407212bb8d0cf1f11a2b881ca263fc19f.doc Page 154 of 158 SearchResponseType.

D- 20050516 Editor Remove Editor’s note: “Darran will send UML to replace ERD”. 07 Updated Jeff Bohren’s email address (throughout). Update text to discuss targetID and containerID as attributes (rather than elements). Applies also to baseTargetID and baseContainerID within SearchQueryType. Applies also to targetID and ID in PSOIdentifierType. #13. Discuss Complex References within Reference Capability section. Explain that capabilities cannot apply to references, and explain that a provider may model each complex relationship as a PSO. Use RacfGroupMembership to illustrate two approaches: 1) independent relationship objects and 2) bound relationship objects. Move elements outside the element that is open content of the element. Updated Appendices and XML snippets to XSD version 16. #15: Correct Jeff Bohren’s company affiliation (was OpenNetworks, now BMC). #15: Correct Gerry Woods’ company affiliation (was IBM, now SOA Software). Miscellanous changes (spec issues #17, 18, 19, 20, 23, 24). #17: Removed example of monotonically increasing integer with rollover as reasonably unique requestID. #18, #20 Removed third person references to “The PSTC…”. #19 Described listTargets as “discovery” operation (rather than as a “bootstrap” operation). #9: Rewrite “Conversational Flow” section. Initially revised, then subsequently removed diagrams of orderly alternation and multiple outstanding requests. Updated text of “RequestID (normative)” to explain that a requestor using a synchronous transport protocol may omit requestID. Update to XSD 17. Request/response element pairs. #70: Discuss effectiveDate for suspend/resume requests. #5: Remove note regarding a “registry” of custom capabilities. #21: Globally change psoId to psoID, targetId to targetID, and containerId to containerID. #71: Discuss QueryClauseType and Logical Operators. Factor discussion of SearchQueryType into an upfront section. Enhance Reference Capability to discuss query clause. Enhance Suspend Capability to discuss query clause.

D- 20050517 Editor Update to XSD 18: 08 (65). SchemaEntityRefType: add targetID attribute.

16507212bb8d0cf1f11a2b881ca263fc19f.doc Page 155 of 158 (67): AddRequestType#targetID: was element now attribute. (67): PSOIdentifierType: containerID now element. (67): TargetType: targetID is now attribute. (71): Define LogicalOperatorType. (67): SearchQueryType: targetID is now attribute. - Move maxReturn from SearchQueryType to SearchRequestType - HasReferenceType now has individual components of reference. Update to XSD 19: - AddRequestType: remove xsd choice. #10: ListTargetsResponse#Capability topic now specifies that any declaration of the reference capability must contain at least one reference definition. #11: ListTargetsResponse#ResourceDefinition canReferTo topic now specifies that any element must specify “targetID” if the contains more than one . In general, targetID may be omitted if a provider exposes only one target. In general, targetID must be specified if a provider exposes multiple targets (except where document structure clearly implies targetID--e.g., where a target contains a supportedSchemaEntity). Reorganized “Complex References” section. Devoted a subsection to each of the three approaches. Added sample ListTargetsResponse for ReferenceData approach. Corrected sample schema in ListTargetsResponse for all three approaches. The content of an instance of PSOIdentifierType depends on the profile that the requestor and provider have agreed to use.

D- 20050523 Editor Update to XSD 20: 09 (81) PSOIdentifierType#containerID now minOccurs=0. (84) Remove maxReturn from SearchQueryType. (88) LookupRequestType#psoID now has default cardinality. Change effectiveDate from “datetime” to “dateTime”. #28. Remove undefined 'isContainer' attribute from 'Organization' and 'OrganizationalUnit' in content within example. (This attribute was intended to occur only in declarations.) #27. Enhanced normative description of 'effectiveDate' attribute of and . Regenerated Table Of Contents. #32 Listed Martin Raepple (SAP), Cory Williams (IBM), and Ian Glazer (IBM) as Contributors. #29 Fix ReferenceDefinition elements closed prematurely in listTargetsResponse example. #30: Change status='succeeded' to status='success'. #33: Globally replace "Capability Schema" with "Capability XSD". Globally replace "Core Schema" with "Core XSD". Change title of

16607212bb8d0cf1f11a2b881ca263fc19f.doc Page 156 of 158 2.1.3.1 from "Schema" to "Target Schema". #39 Added a “Resource Considerations” topic within the Search Capability section. The text within the “Search is not batchable” and “Iterate is not batchable” topics now refers to this “Resource Considerations” topic. Update to XSD 21: (89) Remove CHOICE from SearchQueryType. Rename maxReturn to maxSelect. (85) Rename toPSOID to toPsoID. (86) Rename basePSOID to basePsoID. #41. Correct modification examples to use namespaceURI and path to specify replacement of entire elements (not attributes). #43. Reword section on Batch as a Logical Unit of Work. Rename topic from “A batch is not a logical unit of work” to “No transactional semantics”. #44. Remove references to BatchableRequestType. #46. Make clear that RACF Group Membership is an example of a Complex Reference, not an official part of the Reference Capability. - Rename the topic from “RACF Group Membership” to “Example: RACF Group Membership” - Change the font on the RacfGroupMembership XSD to Arial. - RacfGroupMembershipType should NOT extend spml:ExtensibleType. #47. Empty search result contains no iterator. #51. Iterator element in IterateRequest iterator needs only ID attribute (not count or totalCount). #54. Remove the last remaining reference to capability “registry”. #14. Assume ReferenceDefinitionType contains any number of referenceDataType elements of type SchemaEntityRefType. Discuss referenceDataType within ReferenceDefinition section of Reference Capability. Add “ReferenceDefinition referenceDataType” topic within listTargetsResponse section. D- 20050607 Editor #57. Correct examples: psoID#objectID should be psoID#ID. 10 #14, #56. Remove red font from referenceDataType discussion. #56 Remove red font and strikethrough font (including editor’s notes for issues #6, #7, and #8). Update to XSD 22: #53. Remove Iterator#count and #totalCount. SearchResponse must return error='insufficientResources' if search result exceeds a limit on the provider's part. #55. Add a section within SearchCapability that describes the closeIterator operation. Update to XSD 23: - closeIteratorResponseType is now of type spml:ResponseType

16707212bb8d0cf1f11a2b881ca263fc19f.doc Page 157 of 158 (rather than spmlsearch:SearchResponseType). - allow cardinality to default to IterateRequestType#iterator. - allow cardinality to default for CloseIteratorRequestType#iterator.

#49. Update normative text to reflect removal of ReturnDataType#none. Affects several "PSO and ReturnData" topics.

3498

16807212bb8d0cf1f11a2b881ca263fc19f.doc Page 158 of 158