Page tree
Skip to end of metadata
Go to start of metadata

This page provides an examples of Model web service interface invocations. Please see the IDM Model Web Service Interface page for formal interface definition.

General Notes

  • If there are any policies associated with the user (e.g. a Object Template) midPoint will try to execute that synchronously when a user is changed. This may mean that the operation may take some time. This is usually done in few seconds, but the specific behavior depends on midPoint configuration.
  • All operations use SOAP faults to indicate a problem if possible. However, it is not possible to indicate a problem using a fault and still continue an operations. Therefore there are alternative ways to indicate a problem using operation result structure. There structures are returned in a separate message part of are part of the returned objects. This is a way to complete an operation and still indicate a problem. This is used mostly for non-critical issues (such as warnings).

 

Namespace

Unless specified otherwise all the examples are assuming a common schema namespace as a default namespace. See XML Namespace List for specification of namespace URLs and prefixes used in the examples.

Security

MidPoint supports WS-Security UsernameToken. The token must be placed in Security SOAP header in each request message:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
                   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    soap:mustUnderstand="1">
      <wsse:UsernameToken wsu:Id="UsernameToken-4028eae9-3f47-447f-82f8-8e88becd71d5">
        <wsse:Username>administrator</wsse:Username>
        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss -username-token-profile-1.0#PasswordDigest">PimHMwl8PR5ixPiH5Zggkm/LBa8=</wsse:Password>
        <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">6QDpLmFtpQZ+qzEZg+RX8w==</wsse:Nonce>
        <wsu:Created>2014-11-03T19:03:00.792Z</wsu:Created>
      </wsse:UsernameToken>
    </wsse:Security>
  </SOAP-ENV:Header>
  <soap:Body>
    ...
  </soap:Body>
</soap:Envelope>

The operation will be executed using the identity specified in the Username Token. All the usual model-level authorizations that apply to this identity will also be applied to the web service invocation.

Additional authorization http://midpoint.evolveum.com/xml/ns/public/security/authorization-ws-3#xxx is needed to invoke the server where xxx is the name of the operation (e.g getObject).

Complete Example

Following request message is used to retrieve a representation of user identified by OID 620237a0-6393-11e4-8e1b-3c970e467874:

Complete getObject request
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
                   xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    soap:mustUnderstand="1">
      <wsse:UsernameToken wsu:Id="UsernameToken-4028eae9-3f47-447f-82f8-8e88becd71d5">
        <wsse:Username>administrator</wsse:Username>
        <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss -username-token-profile-1.0#PasswordDigest">PimHMwl8PR5ixPiH5Zggkm/LBa8=</wsse:Password>
        <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">6QDpLmFtpQZ+qzEZg+RX8w==</wsse:Nonce>
        <wsu:Created>2014-11-03T19:03:00.792Z</wsu:Created>
      </wsse:UsernameToken>
    </wsse:Security>
  </SOAP-ENV:Header>
  <soap:Body>
    <m:getObject xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                 xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3">
      <m:objectType>c:UserType</m:objectType>
      <m:oid>620237a0-6393-11e4-8e1b-3c970e467874</m:oid>
      <m:options />
    </m:getObject>
  </soap:Body>
</soap:Envelope>

MidPoint responds:

Complete getObject response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:getObjectResponse xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3">
      <m:object xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                oid="620237a0-6393-11e4-8e1b-3c970e467874" 
                version="22"
                xsi:type="c:UserType">
        <c:name>guybrush</c:name>
        <c:metadata>
          <c:createTimestamp>2014-11-03T21:14:02.704+01:00</c:createTimestamp>
          <c:creatorRef oid="00000000-0000-0000-0000-000000000002" type="UserType"></c:creatorRef>
          <c:createChannel>http://midpoint.evolveum.com/xml/ns/public/model/channels-3#webService</c:createChannel>
        </c:metadata>
        <c:assignment id="1">
          <c:targetRef oid="12345678-d34d-b33f-f00d-987955553535" type="c:RoleType"></c:targetRef>
        </c:assignment>
        <c:activation>
          <c:effectiveStatus>disabled</c:effectiveStatus>
          <c:disableTimestamp>2014-11-03T21:14:02.648+01:00</c:disableTimestamp>
        </c:activation>
        <c:iteration>0</c:iteration>
        <c:iterationToken></c:iterationToken>
        <c:fullName>Guybrush Threepwood</c:fullName>
        <c:givenName>Guybrush</c:givenName>
        <c:familyName>Threepwood</c:familyName>
        <c:emailAddress>guybrush@meleeisland.net</c:emailAddress>
        <c:organization>Pirate Brethren International</c:organization>
        <c:organizationalUnit>Pirate Wannabes</c:organizationalUnit>
        <c:credentials>
          <c:password>
            <c:value xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3">
              <t:encryptedData>
                <t:encryptionMethod>
                  <t:algorithm>http://www.w3.org/2001/04/xmlenc#aes128-cbc</t:algorithm>
                </t:encryptionMethod>
                <t:keyInfo>
                  <t:keyName>4HXeUejV93Vd3JuIZz7sbs5bVko=</t:keyName>
                </t:keyInfo>
                <t:cipherData>
                  <t:cipherValue>bPhgM5fvD3jZVOlcaKu/37pSovOatyT4EVhFi32w8UI=</t:cipherValue>
                </t:cipherData>
              </t:encryptedData>
            </c:value>
          </c:password>
        </c:credentials>
      </m:object>
      <m:result>
        <c:operation>com.evolveum.midpoint.xml.ns._public.model.model_3.ModelPortType.getObject</c:operation>
        <c:status>success</c:status>
        <c:token>1000000000000000370</c:token>
        <c:partialResults>
          <c:operation>com.evolveum.midpoint.model.api.ModelService.getObject</c:operation>
          <c:status>success</c:status>
          <c:params>
            <c:entry key="oid">
              <c:paramValue>620237a0-6393-11e4-8e1b-3c970e467874</c:paramValue>
            </c:entry>
            <c:entry key="class">
              <c:unknownJavaObject>
                <c:class>java.lang.Class</c:class>
                <c:toString>class com.evolveum.midpoint.xml.ns._public.common.common_3.UserType</c:toString>
              </c:unknownJavaObject>
            </c:entry>
            <c:entry key="options">
              <c:unknownJavaObject>
                <c:class>java.util.ArrayList</c:class>
                <c:toString>[]</c:toString>
              </c:unknownJavaObject>
            </c:entry>
          </c:params>
          <c:token>1000000000000000371</c:token>
        </c:partialResults>
      </m:result>
    </m:getObjectResponse>
  </soap:Body>
</soap:Envelope>

Following operation show only the relevant parts of the SOAP body. The other parts are similar to the request and response above.

Read Operations

Get User

The request specifies the object type (which is UserType in this case) and an OID:

getObject request
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  ...
  <soap:Body>
    <m:getObject xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                 xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3">
      <m:objectType>c:UserType</m:objectType>
      <m:oid>620237a0-6393-11e4-8e1b-3c970e467874</m:oid>
    </m:getObject>
  </soap:Body>
</soap:Envelope>

User object is returned in the response:

getObject response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:getObjectResponse xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3">
      <m:object xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                oid="620237a0-6393-11e4-8e1b-3c970e467874" 
                version="22"
                xsi:type="c:UserType">
        <c:name>guybrush</c:name>
        ...
        <c:fullName>Guybrush Threepwood</c:fullName>
        <c:givenName>Guybrush</c:givenName>
        <c:familyName>Threepwood</c:familyName>
        <c:emailAddress>guybrush@meleeisland.net</c:emailAddress>
        ...
      </m:object>
      <m:result>
        ...
      </m:result>
    </m:getObjectResponse>
  </soap:Body>
</soap:Envelope>

The response also contains operation result structure. This result is provided mostly for diagnostic purposes. It is safe to ignore the result part of getObject operation response.

Notes:

  • getObject operation can only retrieve an object identified by OID. If OID is not known then a searchObjects operations can be used instead. However getObject is likely to be much more efficient than searchObjects. Therefore it is recommended for the client application to use searchObjects just for the first time, remember the returned OID and then use OID for subsequent operations. The OID is also persistent and therefore it can provide better data consistency e.g. in case the objects are renamed.

List Users

The searchObjects operation can be used for many purposes. One of the purpose is listing objects of a specified type. The request specifies the object type to list (which is UserType in this case). The request also contains Object Query. In this case the query does not contain any object filter which means we want to get all objects of a specific type. However there may be just too many objects to return in a single response. Therefore the query contains paging specification which limits the returned objects only to specific subset of all the results. In this case the paging specify to only return three objects.

searchObjects request
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  ...
  <soap:Body>
    <m:searchObjects xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                     xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                     xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3">
      <m:objectType>c:UserType</m:objectType>
      <m:query>
        <q:paging>
          <q:orderBy>
             declare default namespace 'http://midpoint.evolveum.com/xml/ns/public/common/common-3';
             name
          </q:orderBy>
          <q:orderDirection>ascending</q:orderDirection>
          <q:maxSize>3</q:maxSize>
        </q:paging>
      </m:query>
      <m:options />
    </m:searchObjects>
  </soap:Body>
</soap:Envelope>

User objects are returned in the response:

searchObjects response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:searchObjectsResponse xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3">
      <m:objectList xmlns:apit="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3">
        <apit:object xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     oid="620237a0-6393-11e4-8e1b-3c970e467874" 
                     version="22"
                     xsi:type="c:UserType">
          <c:name>guybrush</c:name>
          ...
        </apit:object>
        <apit:object xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     oid="d19776da-6441-11e4-8081-3c970e467874" 
                     version="10"
                     xsi:type="c:UserType">
          <c:name>elaine</c:name>
          ...
        </apit:object>
        <apit:object xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     oid="9e42953a-6441-11e4-ac20-3c970e467874" 
                     version="3"
                     xsi:type="c:UserType">
          <c:name>lechuck</c:name>
          ...
        </apit:object>
      </m:objectList>
      <m:result>
        ...
      </m:result>
    </m:getObjectResponse>
  </soap:Body>
</soap:Envelope>

The response also contains operation result structure. This result is provided mostly for diagnostic purposes. It is safe to ignore the result part of searchObjects operation response.

Notes:

  • searchObjects operation returns complete objects. The returned objects also contain OID. The OID can be remembered by the client application and it can be later reused to retrieve object using the getObject operation which is likely to be more efficient.

Search Users

In this case the request contains Object Query with a filter. The filter in this example defines search for objects that have the name property set to value guybrush.

searchObjects request
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  ...
  <soap:Body>
    <m:searchObjects xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                     xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                     xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3">
      <m:objectType>c:UserType</m:objectType>
      <m:query>
        <q:filter xmlns:q="http://prism.evolveum.com/xml/ns/public/query-3">
          <q:equal>
            <q:path>c:name</q:path>
            <q:value>guybrush</q:value>
          </q:equal>
        </q:filter>
      </m:query>
      <m:options />
    </m:searchObjects>
  </soap:Body>
</soap:Envelope>

Each user mush have unique name therefore only one object is returned.

searchObjects response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:searchObjectsResponse xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3">
      <m:objectList xmlns:apit="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3">
        <apit:object xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                     oid="620237a0-6393-11e4-8e1b-3c970e467874" 
                     version="22"
                     xsi:type="c:UserType">
          <c:name>guybrush</c:name>
          ...
        </apit:object>
      </m:objectList>
      <m:result>
        ...
      </m:result>
    </m:getObjectResponse>
  </soap:Body>
</soap:Envelope>

The response also contains operation result structure. This result is provided mostly for diagnostic purposes. It is safe to ignore the result part of searchObjects operation response.

Notes:

  • This use of searchObjects operation can be used to find OID when you know a name of the object.
  • searchObjects operation may be slow. Not all properties are indexed. Avoid using non-indexed properties in the search query. Seach operations that query Shadow Objects are usually transformed to search operations on the resource. This may affect speed of the operation and it can also have impact on the resource.
  • More query examples can be found on XML Object Query page.

Write Operations

MidPoint objects are added, modified and deleted by executing deltas. Delta describes a set of changes in a single object. It can describe a new object to be created, it can describe how an existing object is modified or it can define that an object has to be deleted.

All the write operations are executed by invoking the executeChanges operation.

Add User

Following request initiates addition of a new user object (UserType). The new user object is placed inside a delta.

executeChanges request
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  ...
  <soap:Body>
    <m:executeChanges xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                      xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                      xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
                      xmlns:apit="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <m:deltaList>
        <apit:delta>
          <t:changeType>add</t:changeType>
          <t:objectType>c:UserType</t:objectType>
          <t:objectToAdd xsi:type="c:UserType">
            <c:name>guybrush</c:name>
            <c:assignment>
              <c:targetRef oid="12345678-d34d-b33f-f00d-987955553535" type="c:RoleType" />
            </c:assignment>
            <c:fullName>Guybrush Threepwood</c:fullName>
            <c:givenName>Guybrush</c:givenName>
            <c:familyName>Threepwood</c:familyName>
            <c:emailAddress>guybrush@meleeisland.net</c:emailAddress>
            ...
          </t:objectToAdd>
        </apit:delta>
      </m:deltaList>
    </m:executeChanges>
  </soap:Body>
</soap:Envelope>

MidPoint executes the delta. It creates the user, assigns the roles, applies all the policies, templates, RBAC, mappings, etc. And finally it returns a response:

executeChanges response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:executeChangesResponse xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                              xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                              xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
                              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                              xmlns:apit="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3">
      <m:deltaOperationList>
        <apit:deltaOperation>
          <c:objectDelta>
            <t:changeType>add</t:changeType>
            <t:objectType>c:UserType</t:objectType>
            <t:objectToAdd xsi:type="c:UserType">
              <c:name>guybrush</c:name>
              <c:metadata>
                <c:createTimestamp>2014-11-03T21:14:02.704+01:00</c:createTimestamp>
                <c:creatorRef oid="00000000-0000-0000-0000-000000000002" type="UserType"/>
                <c:createChannel>http://midpoint.evolveum.com/xml/ns/public/model/channels-3#webService</c:createChannel>
              </c:metadata>
              <c:assignment id="1">
                <c:targetRef oid="12345678-d34d-b33f-f00d-987955553535" type="c:RoleType" />
              </c:assignment>
              <c:fullName>Guybrush Threepwood</c:fullName>
              <c:givenName>Guybrush</c:givenName>
              <c:familyName>Threepwood</c:familyName>
              <c:emailAddress>guybrush@meleeisland.net</c:emailAddress>
              ...
            </t:objectToAdd>
            <t:oid>4eb364f4-f6c6-475c-9e64-f47f464c1736</t:oid>
          </c:objectDelta>
          <c:executionResult>
            <c:operation>com.evolveum.midpoint.model.impl.lens.ChangeExecutor.executeDelta</c:operation>
            <c:status>success</c:status>
            ...
          </c:executionResult>
        </apit:deltaOperation>
      </m:deltaOperationList>
    </m:executeChangesResponse>
  </soap:Body>
</soap:Envelope>

The response also contains deltaOperationList structure. Unlike other operations this structure is significant. The executeChanges operation will produce a fault only if something really critical happens - something that does not allow the operation to be executed at all (not even partially). E.g. the fault is produced in case that the request cannot be parsed, it is not allowed, and so on. If the request can be at least partially executed it will be executed. No fault is indicated in such a case even if some parts of the request execution fail. The result part in the deltaOperation element contains operation result that indicates the status and details of each delta execution.

Notes:

  • The OID of created object is returned in the objectDelta structure.
  • The objectDelta structure contains the copy of the object in the form that it exists after the execution. E.g. it contains generated fields such as metadata.
  • The execution of one delta can have side-effects that creates, modifies or deletes other objects. E.g. the example above creates a user which has a role assignment. If the assigned role implies resource accounts such accounts may be created as part of execution of this delta.
  • The executeChanges operation will attempt to execute all the deltas and all the side-effects in a synchronous manner so all the relevant results can be included in the response. However there may be cases when an operation cannot be executed synchronously, e.g. in case that there is an approval process. In such a case the executeChanges operation returns before all the deltas are completed and the result structures inside objectDeltas will indicate status inProgress.

Modify User: fullName

Following request initiates modification of existing user object (UserType). The user is identified by OID and the modification is specified in a delta. The delta specifies replacement of a value for fullName property with a new value which efficiently changes user's full name.

executeChanges request
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  ...
  <soap:Body>
    <m:executeChanges xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                      xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                      xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
                      xmlns:apit="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <m:deltaList>
        <apit:delta>
          <t:changeType>modify</t:changeType>
          <t:objectType>c:UserType</t:objectType>
          <t:oid>c0c010c0-d34d-b33f-f00d-11111111ec1e</t:oid>
          <t:itemDelta>
            <t:modificationType>replace</t:modificationType>
            <t:path>
              declare default namespace 'http://midpoint.evolveum.com/xml/ns/public/common/common-3';
              fullName
            </t:path>
            <t:value xsi:type="t:PolyStringType">Chuck LeChuck</t:value>
          </t:itemDelta>
        </apit:delta>
      </m:deltaList>
    </m:executeChanges>
  </soap:Body>
</soap:Envelope>

MidPoint executes the delta. It modifies the user, executes mapping, executes all the other changes, etc. And finally it returns a response:

executeChanges response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:executeChangesResponse xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                              xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                              xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
                              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                              xmlns:apit="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3">
      <m:deltaOperationList>
        <apit:deltaOperation>
          <c:objectDelta>
            <t:changeType>modify</t:changeType>
            <t:objectType>c:UserType</t:objectType>
            <t:oid>c0c010c0-d34d-b33f-f00d-11111111ec1e</t:oid>
            <t:itemDelta>
              <t:modificationType>replace</t:modificationType>
              <t:path>
                declare default namespace 'http://midpoint.evolveum.com/xml/ns/public/common/common-3';
                fullName
              </t:path>
              <t:value xsi:type="t:PolyStringType">Chuck LeChuck</t:value>
            </t:itemDelta>
            <t:itemDelta>
              <t:modificationType>replace</t:modificationType>
              <t:path>c:metadata/c:modifyTimestamp</t:path>
              <t:value>2014-11-05T18:57:03.865+01:00</t:value>
            </t:itemDelta>
            ...
          </c:objectDelta>
          <c:executionResult>
            <c:operation>com.evolveum.midpoint.model.impl.lens.ChangeExecutor.executeDelta</c:operation>
            <c:status>success</c:status>
            ...
          </c:executionResult>
        </apit:deltaOperation>
      </m:deltaOperationList>
    </m:executeChangesResponse>
  </soap:Body>
</soap:Envelope>

The response also contains deltaOperationList structure. Unlike other operations this structure is significant. The executeChanges operation will produce a fault only if something really critical happens - something that does not allow the operation to be executed at all (not even partially). E.g. the fault is produced in case that the request cannot be parsed, it is not allowed, and so on. If the request can be at least partially executed it will be executed. No fault is indicated in such a case even if some parts of the request execution fail. The result part in the deltaOperation element contains operation result that indicates the status and details of each delta execution.

Notes:

  • Properties in the deltas are specified by using Item Path notation.
  • The objectDelta structure contains the deltas that were actually executed including the deltas of generated fields (such as metadata).
  • The executeChanges operation will attempt to execute all the deltas and all the side-effects in a synchronous manner so all the relevant results can be included in the response. However there may be cases when an operation cannot be executed synchronously, e.g. in case that there is an approval process. In such a case the executeChanges operation returns before all the deltas are completed and the result structures inside objectDeltas will indicate status inProgress.

Modify User: Change Password

Following request initiates modification of existing user object (UserType). The user is identified by OID and the modification is specified in a delta. The delta specifies replacement of a value for credentials/password/value property with a new value.

executeChanges request
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  ...
  <soap:Body>
    <m:executeChanges xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                      xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                      xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
                      xmlns:apit="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <m:deltaList>
        <apit:delta>
          <t:changeType>modify</t:changeType>
          <t:objectType>c:UserType</t:objectType>
          <t:oid>c0c010c0-d34d-b33f-f00d-11111111ec1e</t:oid>
          <t:itemDelta>
            <t:modificationType>replace</t:modificationType>
            <t:path>
              declare default namespace 'http://midpoint.evolveum.com/xml/ns/public/common/common-3';
              credentials/password/value
            </t:path>
            <t:value xsi:type="t:ProtectedStringType">
              <t:clearValue>MIGHTYpirate</t:clearValue>
            </t:value>
          </t:itemDelta>
        </apit:delta>
      </m:deltaList>
    </m:executeChanges>
  </soap:Body>
</soap:Envelope>

MidPoint executes the delta. It modifies the user, executes mappings, propagates the changes to resource accounts, etc. And finally it returns a response:

executeChanges response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:executeChangesResponse xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                              xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                              xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
                              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                              xmlns:apit="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3">
      <m:deltaOperationList>
        <apit:deltaOperation>
          <c:objectDelta>
            <t:changeType>modify</t:changeType>
            <t:objectType>c:UserType</t:objectType>
            <t:oid>c0c010c0-d34d-b33f-f00d-11111111ec1e</t:oid>
            <t:itemDelta>
              <t:modificationType>replace</t:modificationType>
              <t:path>c:credentials/c:password/c:value</t:path>
              <t:value>
                <t:encryptedData>
                  <t:encryptionMethod>
                    <t:algorithm>http://www.w3.org/2001/04/xmlenc#aes128-cbc</t:algorithm>
                  </t:encryptionMethod>
                  <t:keyInfo>
                    <t:keyName>4HXeUejV93Vd3JuIZz7sbs5bVko=</t:keyName>
                  </t:keyInfo>
                  <t:cipherData>
                    <t:cipherValue>W2wQ/06wYkQ9kZg8uKNFqSG3CBfiuFWQOZnJePhybOU=</t:cipherValue>
                  </t:cipherData>
                </t:encryptedData>
              </t:value>
            </t:itemDelta>
            <t:itemDelta>
              <t:modificationType>replace</t:modificationType>
              <t:path>c:metadata/c:modifyTimestamp</t:path>
              <t:value>2014-11-05T18:57:03.865+01:00</t:value>
            </t:itemDelta>
            ...
          </c:objectDelta>
          <c:executionResult>
            <c:operation>com.evolveum.midpoint.model.impl.lens.ChangeExecutor.executeDelta</c:operation>
            <c:status>success</c:status>
            ...
          </c:executionResult>
        </apit:deltaOperation>
      </m:deltaOperationList>
    </m:executeChangesResponse>
  </soap:Body>
</soap:Envelope>

The response also contains deltaOperationList structure. Unlike other operations this structure is significant. The executeChanges operation will produce a fault only if something really critical happens - something that does not allow the operation to be executed at all (not even partially). E.g. the fault is produced in case that the request cannot be parsed, it is not allowed, and so on. If the request can be at least partially executed it will be executed. No fault is indicated in such a case even if some parts of the request execution fail. The result part in the deltaOperation element contains operation result that indicates the status and details of each delta execution.

Notes:

  • The password value property is specified in the deltas by using Item Path notation. In this case it is credentials/password/value.
  • The objectDelta structure contains the deltas that were actually executed including the deltas of generated fields (such as metadata). Even though the input delta has provided cleartext password value the returned delta also returns encrypted value of the password indicating that the password was transparently encrypted in the storage.
  • The executeChanges operation will attempt to execute all the deltas and all the side-effects in a synchronous manner so all the relevant results can be included in the response. However there may be cases when an operation cannot be executed synchronously, e.g. in case that there is an approval process. In such a case the executeChanges operation returns before all the deltas are completed and the result structures inside objectDeltas will indicate status inProgress.

Delete User

Following request initiates deletion of existing user object (UserType). The user is identified by OID and the modification is specified in a delta.

executeChanges request
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  ...
  <soap:Body>
    <m:executeChanges xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                      xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                      xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
                      xmlns:apit="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <m:deltaList>
        <apit:delta>
          <t:changeType>delete</t:changeType>
          <t:objectType>c:UserType</t:objectType>
          <t:oid>c0c010c0-d34d-b33f-f00d-11111111ec1e</t:oid>
        </apit:delta>
      </m:deltaList>
    </m:executeChanges>
  </soap:Body>
</soap:Envelope>

MidPoint executes the delta. It deletes the user, executes mappings, deletes or disables linked accounts, etc. And finally it returns a response:

executeChanges response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <m:executeChangesResponse xmlns:m="http://midpoint.evolveum.com/xml/ns/public/model/model-3"
                              xmlns:c="http://midpoint.evolveum.com/xml/ns/public/common/common-3"
                              xmlns:t="http://prism.evolveum.com/xml/ns/public/types-3"
                              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                              xmlns:apit="http://midpoint.evolveum.com/xml/ns/public/common/api-types-3">
      <m:deltaOperationList>
        <apit:deltaOperation>
          <c:objectDelta>
            <t:changeType>delete</t:changeType>
            <t:objectType>c:UserType</t:objectType>
            <t:oid>c0c010c0-d34d-b33f-f00d-11111111ec1e</t:oid>
          </c:objectDelta>
          <c:executionResult>
            <c:operation>com.evolveum.midpoint.model.impl.lens.ChangeExecutor.executeDelta</c:operation>
            <c:status>success</c:status>
            ...
          </c:executionResult>
        </apit:deltaOperation>
      </m:deltaOperationList>
    </m:executeChangesResponse>
  </soap:Body>
</soap:Envelope>

The response also contains deltaOperationList structure. Unlike other operations this structure is significant. The executeChanges operation will produce a fault only if something really critical happens - something that does not allow the operation to be executed at all (not even partially). E.g. the fault is produced in case that the request cannot be parsed, it is not allowed, and so on. If the request can be at least partially executed it will be executed. No fault is indicated in such a case even if some parts of the request execution fail. The result part in the deltaOperation element contains operation result that indicates the status and details of each delta execution.

Notes:

  • The executeChanges operation will attempt to execute all the deltas and all the side-effects in a synchronous manner so all the relevant results can be included in the response. However there may be cases when an operation cannot be executed synchronously, e.g. in case that there is an approval process. In such a case the executeChanges operation returns before all the deltas are completed and the result structures inside objectDeltas will indicate status inProgress.

 

  • No labels