Showing Users

Use the ShowUser endpoint to retrieve profiles for one or more users.

https://www.glance.net/PAPI/ShowUsers.asp

Parameters

Be sure to include the required authentication parameters with each request.

Also include parameters to describe the user or users you want to retrieve.

Parameter	Type	Required or Optional
PartnerUserID	up to 255 characters	optional
UserAddress	up to 127 characters	optional
UserRole	up to 255 characters	optional
PageCount	integer 1-1000	required
PageStart*	up to 15 characters	optional

*See Response Pagination below

Make Requests to Show Users

Use the Parameters to give the criteria for the user or users you want to show.

To retrieve information about a single user, specify either the PartnerUserID or the UserAddress.

To retrieve information about multiple users, you have several choices.

Omit PartnerUserID, UserAddress, and UserRole. This retrieves all users in your group.
Specify just UserRole. This retrieves all users in the named role in your group.
Specify part of a PartnerUserID. For example, suppose your group's PartnerUserIDs have values like Support1234, Support1235, Sales5678, and Sales5679.
- Example 1: You may give the value Sales* to retrieve all users with PartnerUserIDs starting with Sales.
- Example 2: You may give the value *34 to retrieve all users with PartnerUserIDs ending in 34.
Likewise, select part of the UserAddress. An example might be *.ri.example.glance.net to retrieve users with addresses like adam.ri.example.glance.net and betty.ri.example.glance.net.

If you wish to retrieve information about users with any PartnerUserID or UserRole value, omit the parameter. For users with a particular value, specify it. If you wish to find users with no assigned Role or a missing PartnerUID, specify the special value -none-.

ShowUsers returns the intersection of all the criteria you give. For example, if you specify both PartnerUserID and UserAddress, ShowUsers will only return information about a user if you have both parameters right.

Always give a PageCount value between 1 and 1000.

Responses

Each ShowUsers request returns an XML response document.

If your request fails for some reason, it returns a failure document, described here.

If the request succeeds the document contains the requested information. It looks something like this example.

<?xml version="1.0" standalone="yes"?>
<response>
	<status>OK</status>
	<users>
		<user>
			<startdate>12/20/2001</startdate>
			<partneruserid>Support1234</partneruserid>
			<useraddress>1234.support.example.net</useraddress>
			<userrole>Customer Success</userrole>
			<role>Subscriber</role>
			<userfirst>Adam</userlast>
			<userlast>Benson</userlast>
			<useremail>abenson@example.com</useremail>
			<userphone>212-555-1211<userphone>
			<lastlogin>8/14/2020 12:28:51 PM</lastlogin>
			<lastsession>8/14/2020 12:31:20 PM</lastsession>
			<subscription>true</subscription>
			<suspended>false</suspended>
		</user>
		<user>
			<startdate>8/15/2009</startdate>	
			<partneruserid>Support1235</partneruserid>
			<useraddress>1235.support.example.net</useraddress>
			<userrole>Customer Success</userrole>
			<role>Administrator/Billing</role>
			<userfirst>Betty</userlast>
			<userlast>Anderson</userlast>
			<useremail>eanderson@example.com</useremail>
			<userphone>212-555-1211<userphone>
			<lastlogin>2/18/2021 3:28:51 PM</lastlogin>
			<lastsession>2/18/2021 3:45:21 PM</lastsession>
			<subscription>true</subscription>
			<suspended>false</suspended>
		</user>
	</users>
	<pagestart>12345678</pagestart>   
</response>

NOTE: The time returned for lastlogin and lastsession is in Eastern Standard Time (EST).

This document contains all users matching your criteria. Each user can be found in their own <user> stanza in the XML document under response.users. If a particular value is missing for a particular user, the corresponding XML element is also empty. For example, if Glance has no email address on file for a user, that element looks like this: <useremail></useremail>.

NOTE: ShowUsers presents its results in an unpredictable order. Avoid relying on the ordering of results.

Response Pagination

Because ShowUsers can potentially return a large number of results, you may need to call it multiple times. You must control the maximum number of results returned by each request by giving the PageCount parameter.

In your first request, you omit the PageStart parameter (or set it to a zero-length string). In subsequent requests, you take the <pagestart>12345678</pagestart> value returned by the immediately preceding request and use it to set the PageStart parameter. If the <pagestart></pagestart> value returned from a request is empty it means there are no more results to retrieve.S

NOTE: The `pagestart` values you receive from a sequence of ShowUsers requests are unpredictable. They may vary from request sequence to request sequence, hour to hour, or day to day. Avoid storing and reusing any `pagestart` values you receive. And, please avoid making multiple concurrent requests.

Sample Code

This is pseudocode to retrieve multiple pages of results, with 50 results in each page:

Call ShowUsers with PageCount=100 and a blank PageStart value
Handle each <user> in the set of <users>
While <pagestart></pagestart> is not empty {
  Call ShowUsers with Pagecount=50 and Pagestart set from
  <pagestart></pagestart>
  Handle each <user> in the set of <users>
}

This is an example PERL program to read multiple users from ShowUsers and write them out in csv form.

#!/usr/bin/perl
# sample to use /PAPI/ShowUsers.asp
# confidential and proprietary information of Glance Networks, Inc.
use strict;
use warnings;
use HTTP::Request::Common qw(POST);
use LWP::UserAgent;
use XML::Twig;
use Text::CSV;
use String::Util qw(trim);

my $firstline = 1;
my $csv = Text::CSV->new({ eol => $/ });
my $out = *STDOUT;
my $url = 'https://www.glance.net/PAPI/ShowUsers.asp';
my %params = (  PartnerLogin =>  'Somebody.glance.net',  # authentication
                PartnerPW =>     'REDACTED',                
                PageCount =>     1000,                   # pagination
                PageStart =>     '',
                PartnerUserID => '',                     # items to match if nonblank
                UserAddress =>   '',
                UserRole =>      '',
              );

my $pagestart = '';                                     # updated by sub pagestart below
my $doc = '';

# read each page of PageCount <user> items.
do {
  my $ua = new LWP::UserAgent;
  $params{"PageStart"} = $pagestart;
  my $req = POST $url, [%params] ;

  my $twig= new XML::Twig
              (
               twig_handlers => {
                 '/response/status' =>     \&status,     # handler to check status
                 '/response/pagestart' =>  \&pagestart,  # handler to update $pagestart
                 '/response/users/user' => \&user        # handler to write to csv
               });
  my $res = $ua->request($req);
  if ($res->is_success) {
    $doc = $res->decoded_content;
    $twig->parse($doc);
  }
} while (length($pagestart) > 0);     # continue until <pagestart/> comes back empty


# handler to check status of request
sub status   {
  my( $twig, $item)= @_;
  my $status = $item->text;
  unless ($status eq "OK") {
    print STDERR $doc;
    exit (1);
  }
}
# handler to update $pagestart
sub pagestart   {
  my( $twig, $item)= @_;
  $pagestart = $item->text;
}
# handler to write each <user> to csv
sub user   {
  my( $twig, $item)= @_;
  my @names;
  my @values;
  my $field = $item->first_child;
  while ($field) {
    if ($firstline) {
      push @names, $field->tag;
    }
    push @values, trim($field->text);
    $field = $field->next_sibling;
  }
  if ($firstline) {
    $csv->print($out, \@names);
    $firstline = 0;
  }
  $csv->print($out, \@values);
  $twig->purge();
}

Updated on 13 Jul 2022