From 1fc146b2eb28180b6cc73a384970d3d5b6367b8f Mon Sep 17 00:00:00 2001 From: Pavol Mederly Date: Thu, 10 Jul 2014 14:08:37 +0200 Subject: [PATCH] Enhancing the WSDL documentation a bit. --- .../xml/ns/public/model/model-3.wsdl | 419 ++++++++++++++---- 1 file changed, 337 insertions(+), 82 deletions(-) diff --git a/infra/schema/src/main/resources/xml/ns/public/model/model-3.wsdl b/infra/schema/src/main/resources/xml/ns/public/model/model-3.wsdl index 6c37fd1f935..f491d24022e 100644 --- a/infra/schema/src/main/resources/xml/ns/public/model/model-3.wsdl +++ b/infra/schema/src/main/resources/xml/ns/public/model/model-3.wsdl @@ -29,19 +29,19 @@ - Interface of the IDM Model subsystem. +

Interface of the IDM Model subsystem.

- IDM Model Web interface provides access unified to the identity objects stored in the repository and on the resources. It - abstracts away the details about where and how are the data stored, it hides all the low-level system components. +

IDM Model Web interface provides unified access to the identity objects stored in the repository and on resources. It + abstracts away the details about where and how are the data stored, it hides all the low-level system components.

- Implementation of this interface are expected to enforce a consistency of access control decisions and model, e.g. to enforce - Role-Based Access Control (RBAC). RBAC is only one of many possibly models and this interface may have many implementations. +

Implementations of this interface are expected to enforce a consistency of access control decisions and model, e.g. to enforce + Role-Based Access Control (RBAC). RBAC is only one of many possibly models and this interface may have many implementations.

- Implementations of this interface may automatically derive properties and attributes for objects. E.g. RBAC models may - automatically derive resource accounts attributes based on user role membership. +

Implementations of this interface may automatically derive properties and attributes for objects. E.g. RBAC models may + automatically derive resource accounts attributes based on user role membership.

- This a web service version of the IDM Model Interface represented in WSDL. As such it has some inherent limitations but it is - usable for remote access to the Model services. +

This a web service version of the IDM Model Interface represented in WSDL. As such it has some inherent limitations but it is + usable for remote access to the Model services.

 @@ -64,33 +64,102 @@ schemaLocation="http://midpoint.evolveum.com/xml/ns/public/resource/capabilities-3"/> + + + A request for getObject operation. + + - - - + + + + Type (class) of an object to get. For example, {...common-3}UserType means the user object type. + + + + + + + OID of the object to get. + + + + + + + Options influencing the retrieval and processing of the object. + + + + + + A response from getObject operation. + + - - + + + + The retrieved object. + + + + + + + The result of the operation. + + + + + + A request for executeChanges operation. + + - - + + + + List of object deltas to be applied. + + + + + + + Options influencing the execution of the operation. + + + + + + A response from executeChanges operation. + + - + + + + List of object delta operations (deltas + operation results). OIDs of newly created objects can be found + in these ObjectDeltas (which may or may not be original ObjectDeltas passed to the method). + + + @@ -98,24 +167,58 @@ + + + A request for searchObjects operation. + + - - + + + + Type (class) of an object to get. For example, {...common-3}UserType means the user object type. + + + + - Search criteria (may be null). + Search criteria. If not specified, all objects of a given type are returned. + + + + + + + Options influencing the retrieval and processing of objects. - + + + A response from searchObjects operation. + + - - + + + + List of objects that match given criteria. + + + + + + + The result of the operation. + + + @@ -123,37 +226,99 @@ + + + A request for findShadowOwner operation. + + - + + + + OID of the shadow to look for an owner. + + + + + + A response from findShadowOwner operation. + + - - + + + + Owner of the account (if found). + + + + + + + Operation result covering the operation executed. + + + + + + A request for testResource operation. + + - + + + + OID of the resource that is to be tested. + + + + + + A response from testResource operation. + + - + + + + Result from the resource test. + + + + + + A request for importFromResource operation. + + + - + + + + OID of the resource to be imported from. + + + @@ -167,8 +332,19 @@ + + + A response from importFromResource operation. + + - + + + + Task that is (asynchronously) executing the import procedure. + + + @@ -179,34 +355,96 @@ + + + A request for notifyChange operation. + + - + + + + Description of the change in the external resource. + + + + + + A response from notifyChange operation. + + - + + + + Task, in context of which the event was processed. + + + + + + A request for executeScripts operation. + + - - + + + + Scripts in the XML format. + + + + + + + Scripts in the midPoint Scripting Language (textual) format. Not yet available. + + + - + + + + Options that drive the script execution. + + + + + + A response from executeScripts operation. + + - - + + + + Output of the execution of script(s). + + + + + + + Operation result covering the execution of script(s). + + + @@ -235,11 +473,6 @@ - - @@ -311,15 +544,20 @@ - Returns object for provided OID. - Must fail if object with the OID does not exists. +

Returns object for provided OID. It retrieves the object from an appropriate source + for an object type (e.g. internal repository, resource or both), merging data as necessary, + processing any policies, caching mechanisms, etc. This can be influenced by using options.

- Reference resolution is SUPPORTED by this operation. +

Must fail if object with the OID does not exists.

- Faults: - any SystemFaultType - IllegalArgumentFaultType: wrong OID format - ObjectNotFoundFaultType: object with specified OID does not exists +

Reference resolution is SUPPORTED by this operation.

+ +

Faults (TODO):

+
    +
  • any SystemFaultType
    • +
  • IllegalArgumentFaultType: wrong OID format
    • +
  • ObjectNotFoundFaultType: object with specified OID does not exists
    • +
@@ -328,11 +566,26 @@ - Search for objects in the repository. Searches through all - object types. Returns a list of objects that match search - criteria. +

+ Search for objects. +

+

+ Searches through all object of a specified type. Returns a list of objects that match + search criteria. +

+

+ Note that this method has a very limited scaling capability + as all the results are stored in the memory. DO NOT USE on large datasets. + Recommended usage is only when using queries that cannot return large number + of results (e.g. queries for unique values) or when combined with paging capability. +

+

+ Returns empty list if object type is correct but there are no objects of + that type. Fails if object type is wrong. Should fail if unknown property is + specified in the query. +

- Faults: + TODO Faults: any SystemFaultType IllegalArgumentFaultType: wrong object type SchemaViolationFaultType: unknown property used in search query @@ -406,16 +659,20 @@ - Returns the User object representing owner of specified account - (account shadow). - May return (null?? empty??) object if there is no owner - specified for the account. - - Implements the backward "owns" association between account - shadow and user. Forward association is implemented by property - "account" of user object. +

+ Returns the User object representing owner of specified account (account + shadow). +

+

+ May return null if there is no owner specified for the account. +

+

+ Implements the backward "owns" association between account shadow and + user. Forward association is implemented by property "linkRef" of user + object. +

- Faults: + Faults (TODO): any SystemFaultType IllegalArgumentFaultType: wrong OID format ObjectNotFoundFaultType: object with specified OID does not exists @@ -427,22 +684,22 @@ - WARNING: - This operation should not be here. It is in fact +

WARNING:

+

This operation should not be here. It is in fact just a diagnostics methods from the provisioning interface that need to be accessed from GUI. Do not use it for - anything serious. It will disappear eventually. + anything serious. It will disappear eventually.

- Test the resouce connection and basic resource connector - functionality. +

Test the resouce connection and basic resource connector + functionality.

- This operation will NOT raise fault in case the resource +

This operation will NOT raise fault in case the resource connection fails. It such case it will indicate the failure in the return message, but the operation itself succeeds. The operations fails only if the provided arguments are wrong, - in case of system error, system misconfiguration, etc. + in case of system error, system misconfiguration, etc.

- Faults: + Faults (TODO): any SystemFaultType ObjectNotFoundFaultType: specified Resource definition does not exist @@ -453,19 +710,17 @@ - TODO: update description - - Launch import task that will import all the accounts from the - resource. +

Launch import task that will import all the accounts (or other objects + of specified type) from the resource.

- WARNING: This operation is not considered public. It is a +

WARNING: This operation is not considered public. It is a temporary solution until we have full-featured task management. - It may be removed any time without a warning. + It may be removed any time without a warning.

- DO NOT USE IT unless you are really sure you know what you - are doing. +

DO NOT USE IT unless you are really sure you know what you + are doing.

- Faults: + Faults (TODO): any SystemFaultType ObjectNotFoundFaultType: specified Resource definition does not exist @@ -476,9 +731,7 @@ - TODO: update description - - Trigger change notification. +

Triggers processing of a resource-related change notification.

 @@ -487,6 +740,8 @@ +

Executes one or more midPoint scripts (bulk actions).

+

NOTE: This method is not fully implemented yet.