Deprecated feature

QUERYUSERS

The QUERYUSERS command returns a collection of User objects.

Optional parameters

MerchantNumber
Performing QUERYUSERS on MerchantNumber returns all users associated with that merchant.
Filter
The QUERYUSERS command enables administrators to query users by specifying a user filter. The filter is used by the WCSRealm class to identify a subset of the whole user registry. The WCSRealm allows the filter to specify the character substrings of the user name. For example, calling QUERYUSERS and passing a filter of Smi would result in a list of users including Smith, Smitty and Jones-Smittinger. Note that the WCSRealm treats the user filter as case sensitive. The filter parameter specifies a filter to screen the users being returned. For more information, refer to Valid combination of parameters.

The WCSRealm filters out all non-administrative users by default. This filter is an additional filter for the class of administrative users in WebSphere Commerce.

Note that when the Merchant Administrator requires additional userids, they must be created and assigned by the Payments Administrator.

The following table details the command syntax for the QUERYUSERS command:

Optional keywords Multiple allowed? Value
ETAPIVERSION N 3 (Indicates WebSphere Commerce Payments-or predecessor product-API version: Version 2.1.x, 2.2.x, 3.1.x, 5.5.x, and 5.6.x)
MERCHANTNUMBER Y String form of numeric merchant number.
OPERATION N ASCII character string QueryUsers.
ROLE N The value assigned to each WebSphere Commerce Payments role. For designated values, see Table .
USER N Maximum length is 80 bytes. This is the user name.
RETURNATMOST N Integer in ASCII characters. 32-bit positive integer. The maximum number of users to be returned is 10000.
FILTER N UTF-8 character string with a maximum length of 128 bytes.
Value Meaning Merchant-specific role?
0 Payments Administrator N
1 Merchant Administrator Y
2 Supervisor Y
3 Clerk Y

Valid combination of parameters

The following table illustrates all parameter combinations for the QUERYUSERS command. It also maps who can issue commands for the parameter combinations and what results will be returned.

Note that in most cases, WebSphere Commerce Payments does not check for duplicate parameters. If more than one instance of a parameter is specified, then the last instance will be used.

Parameter combinations Valid? Who* can issue? Return unauthorized users
No parameters specified Yes PA Yes
MERCHANTNUMBER Yes PA/MA No
ROLE Yes PA No
USER Yes All Yes
MERCHANTNUMBER + ROLE Yes PA/MA No
MERCHANTNUMBER + USER Yes All No
ROLE + USER Yes All No
MERCHANTNUMBER + ROLE + USER Yes All No
FILTER Yes PA Yes
FILTER + MERCHANTNUMBER Yes PA/MA No
FILTER + ROLE Yes PA No
FILTER + MERCHANTNUMBER + ROLE Yes PA/MA No
FILTER + USER Yes, but filter will be ignored All Yes
FILTER + MERCHANTNUMBER + USER Yes, but filter will be ignored All No
FILTER + ROLE + USER Yes, but filter will be ignored All No
FILTER + MERCHANTNUMBER + USER + ROLE Yes, but filter will be ignored All No
*PA = Payments Administrator, MA = Merchant Administrator
Parameter combinations
Some key points about QUERYUSERS parameter combinations:
  • When the Username is specified, the filter will be ignored.
  • To return the unauthorized users, you can use only one of the following methods:
    1. Use the filter without the Username
    2. Do not specify any parameters
    3. Query with Username only
Valid
Though a parameter combination may be defined in the QUERYUSERS parameter table as being valid, certain queries may still be invalid. For example, even though a Merchant Administrator can issue a query with Role and Username parameters, the query will be allowed only when the username specified is the Merchant Administrator's username (that is, when the Merchant Administrator is querying himself). For more details on access control for the QUERYUSERS command, see Access control details.
Return unauthorized users
The Return unauthorized users column indicates whether the specified parameter combination can return users who are in the realm, but are not authorized to use WebSphere Commerce Payments. This allows Payments Administrators to query a single user and assign that user WebSphere Commerce Payments access. Note that all calls to QUERYUSERS can return users who are authorized.

Note that a realm may choose not to return all the matching users in the realm, especially if the filter is very unrestrictive. In these cases, the preceding methods will set the User objectCount to the total number of matching realm users. This, in turn, will indicate to the QUERYUSERS caller that the results are not complete and that a more restrictive search filter should be applied.

Access control details

Whether a query is allowed is dependent on the role of the query issuer. For instance:

Payments Administrator
The Payments Administrator can issue a query with any combination of the parameters.
Merchant Administrator

A Merchant Administrator can only query users who:

  • are associated with a merchant number (or numbers) that is managed by the Merchant Administrator

In addition, the Merchant Administrator needs to adhere to the following requirements in his query request:

  • At least one MerchantNumber needs to be specified, and all of the merchant numbers specified should belong to merchants associated with the Merchant Administrator. There is one exception where the merchant number is not required: the Merchant Administrator queries himself.
  • If the Role parameter is specified, it should not contain the role of the Payments Administrator.
Supervisors and Clerks
For all other roles, the user can query himself. In this case, if the filter is specified, the filter will be ignored.