Table of Contents

Search

  1. Preface
  2. Overview, Downloading, and Installing
  3. Administration API
  4. Identity Service API
  5. Screenflow Programming and SDK
  6. ActiveVOS WSHT API
  7. Embedding Request Forms in Standalone Web Pages
  8. XML-JSON for Process Central

7. APIs, SDKs, and Services

7. APIs, SDKs, and Services

Interacting with the Identity Service API

Interacting with the Identity Service API

The Identity Service exposes the operations shown in the following table. You can use SOAP-UI or similar tool (such as the Eclipse's Web Services Explorer) to interact with the Identity Service.
Operation
Description
findRoles
Returns a list of role/group names.
findRolesByPrincipal
Returns a list of role/group names for a principal name.
findIdentitiesByRole
Returns a list of identities associated with role.
findIdentities
Returns a list of identities given an identity search query.
assertPrincipalInQueryResult
Asserts that the a principal is in the resultant identity query. This faults if the principal is not in the result.
assertPrincipalInQueryResultWithResponse
Asserts that a principal is in the resultant identity query and returns the result. This faults if the principal is not in the result.
countIdentities
Returns the total number of identities found in the result after evaluating one or more identity search queries.
findRoles
This operation returns a list of roles available to the Identity Service. A sample
findRoles
SOAP request is similar to:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:iden="http://docs.active-endpoints/wsdl/identity/2007/ 03/identity.wsdl"> <soapenv:Header/> <soapenv:Body> <iden:emptyElement/> </soapenv:Body> </soapenv:Envelope>
The response contains one or more role names, as is shown in the following sample:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <aeidsvc:roleList xmlns:aeidsvc="http://docs.active-endpoints/wsdl/identity/2007/ 03/identity.wsdl"> <aeidsvc:role>loanreps</aeidsvc:role> <aeidsvc:role>loanmgrs</aeidsvc:role> <aeidsvc:role>loancsr</aeidsvc:role> </aeidsvc:roleList> </soapenv:Body> </soapenv:Envelope>
findRolesByPrincipal
This operation returns a list of roles (groups) that a principal belongs to. Here is an example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:iden="http://docs.active-endpoints/wsdl/identity/ 2007/03/identity.wsdl"> <soapenv:Header/> <soapenv:Body> <iden:principalName>loanrep1</iden:principalName> </soapenv:Body> </soapenv:Envelope>
Here is a
findRolesByPrincipal()
response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <aeidsvc:roleList xmlns:aeidsvc="http://docs.active-endpoints/wsdl/identity/ 2007/03/identity.wsdl"> <!-- one or more roles --> <aeidsvc:role>loanreps</aeidsvc:role> </aeidsvc:roleList> </soapenv:Body> </soapenv:Envelope>
findIdentitiesByRole
The
findIdentitiesByRole()
operation return a list of identities associated with a role. Here is an example:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:iden="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl"> <soapenv:Header/> <soapenv:Body> <iden:roleName>loanreps</iden:roleName> </soapenv:Body> </soapenv:Envelope> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <aeidsvc:identityList xmlns:aeidsvc="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl"> <aeid:identity xmlns:aeid="http://schemas.active-endpoints.com/identity/2007/01/identity.xsd"> <aeid:id>CN=John Smith,CN=Users,DC=example,DC=com</aeid:id> <aeid:properties> <aeid:property name="http://www.activebpel.org/ontologies/higgins/2008/ identity-search.owl#firstName">John</aeid:property> <aeid:property name="http://www.activebpel.org/ontologies/higgins/2008/ identity-search.owl#lastName">Smith</aeid:property> <aeid:property name="http://www.activebpel.org/ontologies/higgins/2008/ identity-search.owl#email">john.smith@example.com</aeid:property> <aeid:property name="http://www.activebpel.org/ontologies/higgins/2008/ identity-search.owl#userName">jsmith</aeid:property> </aeid:properties> <aeid:roles> <aeid:role>loanreps</aeid:role> <!-- Additional 'aeid:role' elements --> </aeid:roles> </aeid:identity> <!-- Additional 'aeid:identity' elements --> </aeidsvc:identityList > </soapenv:Body> </soapenv:Envelope>
Notice the
<aeid:identity>
element in the result set. Within this element, the
<aeid:id>
represents the distinguished name (DN) for an LDAP based identity service providers. The
<aeid:identity>
also has one or more
<aeid:property>
elements, representing the identity service user model attributes.
For example, in the following figure, the LDAP (Active Directory)
givenName
attribute is mapped to
firstName
(in the ActiveVOS domain). This means, the LDAP
givenName
attribute is available using the
http://www.activebpel.org/ontologies/higgins/2008/identity-search.owl#firstName
property name.
To extract the email address from the result (say assigned to variable
$identityList
), use the following expression:
$identityList/aeid:identity/aeid:properties/aeid:property [@name='http://www.activebpel.org/ontologies/higgins/2008/ identity-search.owl#email']/text()
findIdentities
This operation returns a list of identities based on an identity query. An identity query (
<iden:identityQuery>
) has include and exclude elements. The roles or principals listed within the include element are included in the result set while the ones listed within the exclude element are excluded.
Here is a sample request that constructs a query that fetches all loanreps members except for loanrep2 and also includes user loancsr:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:iden="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl"> <soapenv:Header/> <soapenv:Body> <iden:identityQuery> <iden:include> <iden:group>loanreps</iden:group> <iden:user>loancsr</iden:user> </iden:include> <!-- Additional iden:include elements. --> <iden:exclude> <iden:user>loanrep2</iden:user> </iden:exclude> <!-- Additional iden:exclude elements. --> </iden:identityQuery> </soapenv:Body> </soapenv:Envelope>
The response contains zero or more
<aeid:identity>
elements.:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <aeid:identityResultSet xmlns:aeid="http://schemas.active-endpoints.com/ identity/2007/01/identity.xsd"> <aeid:totalRowCount>3</aeid:totalRowCount> <aeid:completeRowCount>true</aeid:completeRowCount> <aeid:identities> <aeid:identity> <!-- aeid:identity child elements --> </aeid:identity> <!-- Additional aeid:identity elements --> </aeid:identities> </aeid:identityResultSet </soapenv:Body> </soapenv:Envelope>
assertPrincipalInQueryResult
The
assertPrincipalInQueryResult
operation checks to see if the a principal exists for an identity query. Restated, it checks if the principal exists in the result set of the evaluating the identity query. This operation faults if the principal is not in the result set.
Here is a sample request to check if user user1 is a member of either the loanreps or loanmgrs groups:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:iden="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl"> <soapenv:Header/> <soapenv:Body> <iden:principalQueryAssertion> <iden:principalName>user1</iden:principalName> <iden:identityQuery> <iden:include> <iden:group>loanreps</iden:group> <iden:group>loanmgrs</iden:group> </iden:include> </iden:identityQuery> <!-- Additional iden:identityQuery elements. --> <iden:principalQueryAssertion> </soapenv:Body> </soapenv:Envelope>
If
assertPrincipalInQueryResult()
operation faults, the response is similar to:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <Fault xmlns="http://schemas.xmlsoap.org/soap/envelope/"> <faultcode xmlns:ns1="http://docs.active-endpoints/wsdl/identity/ 2007/03/identity.wsdl" xmlns="">ns1:searchFault</faultcode> <faultstring xmlns=""/> <faultactor xmlns=""/> <detail xmlns=""> <aeidsvc:identityFault xmlns:aeidsvc="http://docs.active-endpoints/ wsdl/identity/2007/03/identity.wsdl"> <aeidsvc:code>10</aeidsvc:code> <aeidsvc:message>Principal user1 was not found in query.</aeidsvc:message> </aeidsvc:identityFault> </detail> </Fault> </soapenv:Body> </soapenv:Envelope>
assertPrincipalInQueryResultWithResponse
This is similar to the previous operation; that is, it asserts that a principal is returned as part of one of the identity queries. All of the identity queries are evaluated and the response indicates which results contained the principal.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:iden="http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl"> <soapenv:Header/> <soapenv:Body> <iden:principalQueryAssertionWithResponse> <iden:principalName>user1</iden:principalName> <iden:identityQuery> <iden:include> <iden:group>loanreps</iden:group> <iden:group>loanmgrs</iden:group> </iden:include> </iden:identityQuery> <!-- Additional iden:identityQuery elements. --> <iden:principalQueryAssertionWithResponse> </soapenv:Body> </soapenv:Envelope>
The response contains a 1-based index to the first identity query that contained the principal. For example, if the request element (
<iden:principalQueryAssertionWithResponse>
) has three identity queries (
<iden:identityQuery>
elements), and the principal was found in the second, the response looks similar to:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <aeidsvc:assertionQueryResponse xmlns:aeidsvc="http://docs.active-endpoints/wsdl/identity/2007/ 03/identity.wsdl">2</aeidsvc:assertionQueryResponse> </soapenv:Body> </soapenv:Envelope>
countIdentities
This operation returns the total number of identities matched after evaluating all of the identity queries. Here is a sample request and response:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:iden="http://docs.active-endpoints/wsdl/identity/ 2007/03/identity.wsdl"> <soapenv:Header/> <soapenv:Body> <iden:principalQueryAssertionWithResponse> <iden:identityQuery> <iden:include> <iden:group>loanreps</iden:group> <iden:group>loanmgrs</iden:group> </iden:include> </iden:identityQuery> <!-- Additional iden:identityQuery elements. --> <iden:principalQueryAssertionWithResponse> </soapenv:Body> </soapenv:Envelope> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <aeid:identitiesCount xmlns:aeid="http://docs.active-endpoints/wsdl/identity/2007/03/ identity.wsdl">6</aeid:identitiesCount> </soapenv:Body> </soapenv:Envelope>