SOAP API - listCandidateResources

The table summarizes the SOAP API - listCandidateResources.

Request Uses the listCandidateResources element (from the DirectoryService schema)
Parameter notes
  • container-id: identifies the LDAP container from which the candidates are to be listed.
  • include: determines what entries should be included in the response. Can be:
    • EXISTING: include only entries from which a resource has already been created.
    • NON-EXISTING: include only entries from which no resource has yet been created.
    • ALL: include both existing and non-existing candidate resources. This is the default.
    • INVALID: include only the "invalid" resources. These are typically "missing" resources, which means that the resource’s DN in the LDAP source has changed and no longer matches the DN that had previously been retrieved for the resource from the LDAP source. (Note that lists of invalid resources cannot be paged; the request can be made to page, but it will not be honored.)
  • page-size: Limits the number of candidate resources returned to the number specified. If not specified, all results are returned.

    Note - The LDAP server may impose its own page-size limit. If you specify a number in this parameter that is larger than a size limit specified on the LDAP server (which is commonly 1000), the LDAP server limit takes precedence.

  • bookmark: only applicable when "paging" the results (that is, when the page-size parameter is passed). This parameter is not passed in the first call to get paged results; it is obtained from the response to the first call, then passed in subsequent calls to get additional pages of results.
Response Returns a listCandidateResourcesResponse element (from the DirectoryService schema).
  • guid: the GUID is listed only for candidates that have already been created as resources.
  • name: the name of an existing resource, or the name that will be assigned (by default) to the resource created from this candidate entry.
  • bookmark: this value is returned in the response when page-size is included in the request. The bookmark value is passed in subsequent requests for paged results. If the bookmark returns empty in the response, it means the end of the result set has been reached.
  • estimated-size: this is returned in the response to provide an estimated number of candidate resources. This is returned only from paged requests, and only after the first request. Also note that this is not supported by all LDAP servers (the Apache LDAP server does not support it); when not supported, it returns 0.
Example

First Request Using Paging

Request: 
<soapenv:Body>
      <dir:listCandidateResources container-id="2" include="ALL" page-size="10"/>
</soapenv:Body>
Response: 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <listCandidateResourcesResponse bookmark="EMd7pA==" container-id="2" estimated-size="0" include="ALL" xmlns="http://directory.api.de.bpm.tibco.com">
         <candidate ldap-alias="deLdap5" ldap-dn="UID=acresswell, OU=employees, O=goCarInsuranceHeadOffice" name="Aaron Cresswell" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=adownes, OU=employees, O=goCarInsuranceHeadOffice" name="Aaron Downes" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=ahardy, OU=employees, O=goCarInsuranceHeadOffice" name="Aaron Hardy" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=ahughes, OU=employees, O=goCarInsuranceHeadOffice" name="Aaron Hughes" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=arooney, OU=employees, O=goCarInsuranceHeadOffice" name="Adam Rooney" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=asmith, OU=employees, O=goCarInsuranceHeadOffice" name="Adam Smith" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=awatts, OU=employees, O=goCarInsuranceHeadOffice" name="Adam Watts" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=awilson, OU=employees, O=goCarInsuranceHeadOffice" name="Adam Wilson" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=amoses, OU=employees, O=goCarInsuranceHeadOffice" name="Adie Moses" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=aahmed, OU=employees, O=goCarInsuranceHeadOffice" name="Adnan Ahmed" xmlns=""/>
      </listCandidateResourcesResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example

Next Call to Get Paged Results (using bookmark parameter)

Request: 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dir="http://directory.api.de.bpm.tibco.com">
   <soapenv:Header/>
   <soapenv:Body>
      <dir:listCandidateResources bookmark="EMd7pA==" container-id="2" include="ALL"  page-size="10"/>
   </soapenv:Body>
</soapenv:Envelope>
Response: 
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <listCandidateResourcesResponse bookmark="EMd7pA==" container-id="2" estimated-size="0" include="ALL" xmlns="http://directory.api.de.bpm.tibco.com">
         <candidate ldap-alias="deLdap5" ldap-dn="UID=aleijer, OU=employees, O=goCarInsuranceHeadOffice" name="Adrian Leijer" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=aboothroyd, OU=employees, O=goCarInsuranceHeadOffice" name="Aidy Boothroyd" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=asodje, OU=employees, O=goCarInsuranceHeadOffice" name="Akpo Sodje" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=abrown, OU=employees, O=goCarInsuranceHeadOffice" name="Alan Brown" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=acrawford, OU=employees, O=goCarInsuranceHeadOffice" name="Alan Crawford" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=agoodall, OU=employees, O=goCarInsuranceHeadOffice" name="Alan Goodall" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=agowling, OU=employees, O=goCarInsuranceHeadOffice" name="Alan Gowling" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=ajones, OU=employees, O=goCarInsuranceHeadOffice" name="Alan Jones" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=amcneill, OU=employees, O=goCarInsuranceHeadOffice" name="Alan Mcneill" xmlns=""/>
         <candidate ldap-alias="deLdap5" ldap-dn="UID=amiller, OU=employees, O=goCarInsuranceHeadOffice" name="Alan Miller" xmlns=""/>
      </listCandidateResourcesResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>