Showing Users

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

Parameters

Parameter Type Required or Optional
Authentication PartnerLogin required
PartnerPW PartnerPW or PartnerAuth required
PartnerAuth PartnerPW or PartnerAuth required
User 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 User 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 will retrieve all users in your group.
  • Specify just UserRole. This will retrieve 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.

Response Handling

Each ShowUsers call returns an XML response document.

Calls can fail for a number of reasons. If a call fails the document is:

<?xml version="1.0" standalone="yes"?>
<response>
    <status>FAIL</status>
    <errcode>nnn</errcode>
    <msg>msg</msg>
    <field>field</field>
</response>

Failure can occur if authentication fails, or if one or more parameters are incorrect. Failure also occurs if no users matching your criteria are found.

If the call 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>
			<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>
			<subscription>true</subscription>
			<suspended>false</suspended>
		</user>
		<user>
			<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>
			<subscription>true</subscription>
			<suspended>false</suspended>
		</user>
	</users>
	<pagestart>12345678</pagestart>   
</response>

This document contains all users matching your criteria. Each user can be found in their own 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>.

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 call by giving the PageCount parameter.

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

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 a 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://local.myglance.org/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();
}

By continuing to use the site, you agree to the use of cookies. Learn More