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
Smiwould result in a list of users includingSmith,SmittyandJones-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:
- Use the filter without the Username
- Do not specify any parameters
- 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.