Query operations

Query operations are used to search entities managed by nevisIDM. The queries offered by the service are listed below. Every query accepts a template object of the same type as the query result(s). The fields that can be used for the search and the type of search are also specified per query. Searches are allowed on multiple fields as long as they are defined on the same entity (e.g., a user's first name and surname can be combined).

Queries are always read-only and do not change any states in nevisIDM. Dark-shaded operations have not been implemented yet. Basic query operations support customer-specific properties too. Note that searching for encrypted property values is not supported.

List<Client>queryClients(ClientQuery q)

Category: Query

Search for clients. Wildcard search:

• client.name
• client.remarks
• client.displayName.value

Exact search:

• client.extId
• client.displayName.lang

Supported sort attributes (parameter sortByField): name, displayName, ctlModDat

List<Application>queryApplications(ApplicationQuery q)

Category: Query

Search for applications. Wildcard search:

• application.name
• application.url
• property values (if property has scope onApplicationGlobal)

Exact search:

• application.extId

Supported sort attributes (parameter "sortByField"): name, url, desription, displayname (use language of user or, if not available, the application‘s default language), displayname_<language code> (where language code is DE, FR, IT, EN).

This query does not support the application.displayName.lang parameter.

List<Role>queryRoles(RoleQuery q)

Category: Query

Search for application roles.

Wildcard search:

• role.name
• role.applicationName
• property values (if property has scope onRoleForApp)

Exact search:

• role.extId

Supported sort attributes (parameter sortByField): name, application, description, applicationDisplayName, ctlModDat

When searching by properties, the attribute applicationName or scopeName of the property has to be set. In this case, wildcard characters are not supported in the attribute applicationName. When both attributes are set, they must have the same value.

This query does not support the application.displayName.lang parameter.

List<Policy>queryPolicies(Policy p, Unit u)

Category: Query

Search for policies. If the unit is given, the credential policies that are assigned to the unit are returned. If unit is not given, the client‘s policies will be returned.

Wildcard search:

• policy.name

Exact search:

• policy.extId
• policy.type
• unit.extId

Currently, not supported as search criteria are: policy.description and policy.config.

The unit has always been defined by means of the exact external ID.

Supported sort attributes (parameter sortByField): name, description, type, ctlModDat

List<User>queryUsers(UserQuery q)

Category: Query

Search for users. Wildcard search is possible for all user attributes as well as property values (except properties of scope onApplicationGlobal).

In case of onProfileForApp or onRoleForApp properties, the name of the application has to be set on the attribute scopeName of the property.

To search for users that explicitly have not set a value for a certain property, define the property but set its value to NULL (i.e., do not specify the value at all on the web service request object). queryUsers can find users that hold specified values of a specified certificate or generic credential property. For the latter, the credential type GENERIC has to be set explicitly. Otherwise, the implementation falls back to the default and assumes certificate properties.

Exact search:

• user.extId
• user.state
• user.sex
• user.country
• user.birthDate
• user.language
• user.stateChangeReasonCd
• user.isTechnicalUser
• user.postOfficeBoxNumber
• user.profile.extId
• user.profile.name
• user.profile.role.name
• user.profile.unit.extid
• user.profile.enterpriseRole.extid

Wildcard search:

• user.profile.name
• user.profile.unit.name
• user.profile.role.applicationName

Interval search:

• user.birthDateFrom
• user.birthDateTo
• user.validFromHi
• user.validFromLow
• user.validToHi
• user.validToLow
• queryUsers also supports searching by credentials.

It supports searching by general credential attributes:

• user.credential.type
• user.credential.state

For example if we search for the credential type PASSWORD, queryUsers will list all users who have a password credential.

It also supports searching by attributes that are specific to certain credential types. The following attributes are supported:

• Certificates: user.certificate.subjectDn / user.certificate.issuerDn

Mobile signatures:

• user.mobileSignature.msisdn
• user.mobileSignature.identificator
• user.mobileSignature.msspIdentifier
• user.mobileSignature.properties

SAML federations:

• user.samlFederation.issuerNameId
• user.samlFederation.issuerNameIdFormat
• user.samlFederation.subjectNameId
• user.samlFederation.subjectNameIdFormat
• user.samlFederation.properties

Security questions:

• user.securityQuestions.answers.question.extId
• user.securityQuestions.properties

The result will contain all users who have an answer to the defined security question.

Context password:

• user.credential.context

You can find examples for searching by credential attributes in the chapter queryUsers.

List<Credential>queryCredentials(CredentialQuery q)

Category: Query

Search for credentials.

Wildcard search:

• credential.policyName
• credential.properties

Exact search:

• credential.state
• credential.extId
• credential.type (required when searching for credential.value)
• credential.value
• credential.userExtId
• credential.policyExtId
• credential.name
• credential.context
• credential.properties

Null search (xsi:nil=true):

• credential.userExtId

Supported sort attributes (parameter sortByField): user, userId, subject, issuer, fingerprint, issuer_namd_id, subject_name_id, state, validFrom, validTo, ctlModDat.

For the credential types CERTIFICATE, GENERIC, MOBILE SIGNATURE, SAML FEDERATION and SECURITY_QUESTIONS, searching by property value is supported. In this case, the credential type has to be set. Searching by the context attribute is only supported for context password credentials. The credential property values are returned if the credential detail level is at least MEDIUM and the property detail level is not EXCLUDE.

Properties are supported for the credential types CERTIFICATE, GENERIC, MOBILE SIGNATURE, SAML FEDERATION and SECURITY QUESTION. The credential extensions are returned if the credential detail level is at least MEDIUM and the related detail level is not EXCLUDE. Only the credential types CERTIFICATE, MOBILE SIGNATURE, SAML FEDERATION, OATH and SECURITY QUESTION have extensions.

List<Profile>queryProfiles(ProfileQuery q)

Category: Query

Search for profiles.

Wildcard search:

• profile.name
• profile.remarks
• profile.properties (searching by properties with scope onProfileGlobal is supported)

Exact search:

• profile.extId
• profile.state
• profile.unit.extId

Supported sort attributes (parameter sortByField): user, userId, subject, issuer, fingerprint, issuer_name_id, subject_name_id, state, validFrom, validTo, ctlModDat, cred_Extid, vascoCRSupported, vascoROSupported

List<Unit>queryUnits(UnitQuery q)

Category: Query

Search for units. The search for units based on onUnitGlobal properties is supported as well.

Wildcard search:

• unit.name
• unit.location
• unit.description
• unit.displayName
• unit.displayAbbreviation
• unit.properties.value

Exact search:

• unit.extId
• unit.state
• unit.policyName

Recursive search:

• unit.parentExtId Enumerates all (transitive) parents of the specified unit.

Note that if a language is specified in the query of the exact search for either unit.displayName or unit.displayAbbreviation, all the dict entries are only returned in the specified language. If no language is specified, the exact search returns the dict entries unit.displayName, unit.displayAbbreviation as well as unit.localizedName in all available languages. The recursive search does not support any language parameters for dict entries. The system always uses the default language configured in the file nevisidm-prod.properties in the query ).

List<Property>queryProperties(PropertyQuery q)

Search for property definitions.

Wildcard search:

• property.name

Exact search:

• property.scope

The allowed values of the enum properties are returned if the property detail level is MEDIUM at least.

List<Template> queryTemplates(TemplateQuery q)

Category: Query

Search for templates.

Exact search:

• template.extId
• template.commEventType
• template.documentType
• template.precedence

The language-dependent contents of the template are returned only if the detail level is HIGH.

Note: Consider that the template query results will be held in memory, including the template content if called with detail level HIGH. You may thus reach nevisIDM‘s memory limitations if your query returns many templates with large binary content.

Supported sort attributes (parameter sortByField): docType, eventType, tmplColl, precedence, ctlModDat

List<EnterpriseRole> queryEnterpriseRoles (EnterpriseRoleQuery q)

Category: Query

Search for enterprise roles. Return assigned application roles also, depending on detail level.

Wildcard search:

• enterpriserole.name
• property values (if property has scope on ERoleGlobal)

Exact search:

• enterpriserole.extId

Supported sort attributes (parameter sortByField): name, description, displayname (use language of user or, if not available, the application‘s default language), displayname_<language code> (where language code is DE, FR, IT, EN). This query does not support the enterpriserole.displayName.lang parameter.

List<PersonalQuestion> queryPersonalQuestions (PersonalQuestionQuery q)

Category: Query

Search for personal questions.

Wildcard search:

• personalQuestion.description
• personalQuestion.displayName
• personalQuestion.content

Exact search:

• personalQuestion.extId
• personalQuestion.state
• personalQuestion.language

Supported sort attribute: extid, displayName, description, content, state, ctlmoddat

List<ApplicationClientAssignment> queryApplicationClientAssignments(ApplicationClientAssignmentQuery)

Category: Query

Search for application client assignments.

Exact search:

• application.extId
• client.extId

Wildcard search:

• application.name
• client.name

The query considers application and client data rooms of the caller user's authorization.

This query does not support the client.displayName.lang and the application.displayName.lang parameters.

List<User> getUsersByLoginId(get)

Category: Getter

Returns a list of users based on a list of login IDs (loginId).

Note: If the search.dataroomrestrictions.enabled parameter is true in the caller's client policy, the unit data room restrictions will be applied to the query. This means that the query will only return those users the caller has permission for based on the data room restrictions.

If fine-grained permissions are defined on the UserView elementary right, the result will contain only the attributes the caller user is authorized for (for more information about fine-grained permissions see the chapter "Fine-grained permissions of nevisIDM roles").

List<User> getUsersByExtId(get)

Category: Getter

Returns a list of users based on a list of user external IDs (extId).

Note: If the search.dataroomrestrictions.enabled parameter is true in the caller's client policy, the unit data room restrictions will be applied to the query.

If fine-grained permissions are defined on the UserView elementary right, the result will contain only the attributes the caller user is authorized for (for more information about fine-grained permissions see the chapter "Fine-grained permissions of nevisIDM roles").

List<User> getUsersByProfileExtId(get)

Category: Getter

Returns a list of users based on a list of profile external IDs (profileExtId).

Note: If the search.dataroomrestrictions.enabled parameter is true in the caller's client policy, the unit data room restrictions will be applied to the query.

If fine-grained permissions are defined on the UserView elementary right, the result will contain only the attributes the caller user is authorized for (for more information about fine-grained permissions see the chapter "Fine-grained permissions of nevisIDM roles").

User getCaller()

Category: Getter

Returns the User object of the caller (can be used by portal applications to return info about authenticated user).

List<Unit> getUnits(extIds, lang)

Category: Getter

Retrieves units by their external IDs.

• extIds: list of unit external IDs that should be retrieved

• lang: language code (DE, EN, IT, FR). It defines in which language the language dependent unit attributes are returned. If lang is not specified, nevisIDM‘s default language is used.

By defining maxRecursionDepth on the request, child units of the requested units are returned as well. By default, maxRecursionDepth is "0", thus no child units are returned.

File getDocumentForCredential(String credentialExtId, CommEventType eventType, FileType fileType)

Category: Getter

Retrieves the document belonging to a certain credential for a certain communication event.

List<User> getAuthorizers(String profileExtId, String roleExtId)

Category: Getter

Returns all users who are authorized to assign the role identified by the roleExtId to the profile identified by the profileExtId.

A user is authorized to assign a role to a profile if he has the functional authorization with the corresponding data room.

If fine-grained permissions are defined on the UserView elementary right, the result will contain only the attributes the caller user is authorized for (for more information about fine-grained permissions see the chapter "Fine-grained permissions of nevisIDM roles").

List<EnterpriseRole> getEnterpriseRoles (extIds, lang)

Category: Getter

Retrieves enterprise roles by their external IDs.

• extIds: list of enterprise role external IDs that should be retrieved

• lang: language code (DE, EN, IT, FR). It defines in which language the language-dependent enterprise role attributes are returned. If lang is not specified, nevisIDM‘s default language is used.

List<PersonalQuestion> getPersonalQuestions (extIds, lang)

Category: Getter

Retrieves personal questions by their external IDs.

• extIds: list of personal question external IDs that should be retrieved
• lang: language code (DE, EN, IT, FR). It defines in which language the language-dependent attributes (displayName and content) are returned. If the language is not specified, nevisIDM‘s default language is used.