Administration REST API Implementation
“The productivity of work is not the responsibility of the worker but of the manager.” - Peter Drucker
The Administration API provides developers with the ability to manage users, user groups, accounts, products and licenses, and to access audio and meeting data not available within the GoToMeeting or other product-specific APIs. The Admin API supports GoToMeeting, GoToWebinar, GoToTraining, GoToAssist, and OpenVoice.
The Administration API enables developers to work directly with accounts, users, and product settings, and generate a variety of reports. The API automatically operates with GoToMeeting, GoToTraining, GoToWebinar and OpenVoice. You do not need to define a separate app for it. The Admin API does not currently support the GoToAssist calls.
Administration API Resources
The Administration API allows you to manage aspects of key resources. Accounts can be modified with attributes and products can be accessed to update key settings. Users and user licenses can be managed and these can be organized into groups for easy updates. Meetings and other resources can be accessed for reporting purposes.
IMPORTANT: The Administration API only works with “Global” platform accounts. When you get the organizerKey in Step 4 of Getting Started, you will receive a result that includes the platform value. If this is Global, you’re good to go. If it displays any other value, contact firstname.lastname@example.org.
For complete resource tables, see Administration API Resources.
Accounts and Attributes
Accounts provide unique identification for organization using Getgo services. They are created and deleted outside the Administration API. However, accounts can be read and updated, and users can belong to multiple accounts.
Multiple account support enables users who access Getgo accounts through more than one organization (e.g., consultants, developers, freelance trainers, etc.) to have accounts with each organization they work with. The first account a user signs up for is the user's primary account. Additional accounts are secondary accounts. (A user has the same organizerKey across all accounts.) Admins for the primary accounts who have SUPER_USER or MANAGE_USERS adminRoles can update user data for that account, but not for the secondary account. To make these user updates in the primary account, use the Update User call. The admins for the secondary accounts also cannot update the secondary account user core data (firstName, lastName, email, and locale), but can update other user data. If a user's core identity in a secondary account must be modified, contact the Customer Service Representative for that account. (Admin users with the capability to make core user identity changes are included will have the field identityReadOnly = false in the Get User or Get All Users response. All other users will return identityReadOnly = true.)
User account data can be extended using Attributes. Access to the Attributes and update calls is limited to the SUPER_USER role. An attribute is a named key you can add to the Account object and then update for each user. You can define one or more attributes for your accounts, and modify and delete them. Once an attribute is defined, it can be populated for any user’s account.
Attributes consist of a named object (attributeName) in the Account object and a related attribute key (attributeNameKey) in the User object. Some attributes exist by default such as lastName and email. These attributes are locked and cannot be deleted or changed, and each new User object created requires them to be populated. You can define any additional attributes you need for your accounts, for example, employee ID, title, department, etc. Once you define the attributeName in the Account object, you can assign attributeValues to it for each User object with the Add User call.
Users, Roles, Licenses and Groups
Users are defined by a unique userKey and include user specifics (names, locale, email, etc.), the products they use and license keys, their administrative roles, and any groups they belong to. Users can be added, updated and deleted. Most reporting is parsed by user. The administrative roles are invoked when a user is authenticated and apply across all objects and processes. The roles are:
- SUPER_USER – Can create other Administrator or Manager roles; receives all other Admin roles; can modify Account settings
- MANAGE_USERS – Create, delete, and modify users
- MANAGE_SEATS – Distribute licenses to existing users
- MANAGE_SETTINGS – View and modify product specific settings for users (not Account settings)
- MANAGE_GROUPS – Create, delete, and modify groups
- RUN_REPORTS – Run reports
Each user has one or more Getgo product accounts. Each of these accounts is licensed to that user and the user is assigned a license key. The products and licenses are managed in the user object. Users also have default settings for each product.
Groups are an optional hierarchy one level deep. You can define multiple parent-level groups and each of these can have multiple child groups. A child group can belong to just one of the parent groups. Groups are a way to manage users. You can make product settings, update or add licenses, and report by group. You define groups in the user object and then assign users to parent or child groups.
Parameters can be included in the URLs of selected requests to set date ranges; filter, sort and paginate output; and otherwise modify the behavior of a request. All reports, and a few other calls, require fromDate and toDate parameters. Any multi-record GET call – for users, groups, licenses, meetings, templates, or attributes – can be optionally filtered, sorted, and paginated. Any call that modifies user license assignments sends a notification email to each affected user by default; a suppressEmail parameter allows you to skip this step. For the Create Users request, you can force the error status when duplicate emails are detected to a 200 OK by including allOrNothing=false; if set to true, duplicate emails return a 409 Conflict response.
Request parameters are added following a question mark in the URL as shown:
curl -X GET \ https://api.getgo.com/admin/rest/v1/users?pageSize=10&offset=10&filter=(email="(?i).*JGould@jg.org.*") | (firstName="(?i).*Janis.*") | (lastName="(?i).*Gould.*")&ascending=firstName=true \ -H 'Accept: application/json' -H 'Content-type: application/json' -H 'Authorization: OAuth oauth_token= ZlUe11FakEyCWxtOkeN3wk0uTKuL'
Filter expressions are boolean expressions on resource or object fields and support match operators '=' and '!=' based on a regular expression as well as boolean operators '&' and '|' to combine match results. Use precedence terminals '(' and ')' to set evaluation order. Resource fields names must only include alphanumeric characters, dots '.', and underscores '_'. Regular expression strings must be surrounded by double quotes '"' and may include all characters except double quotes.
Any resource field can be referenced in a filter expression. Resource fields are case-sensitive. Non-existent and null resource fields are evaluated as empty string. See http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html (link is external) for regular expression syntax.
To perform filtering in REST calls, the 'filter' request parameter is required. The value of the parameter is a url-encoded filter expression. The equal '=' character url-encoded is '%3D', the double quote character '"' url-encoded is '%22', and the space character ' ' url-encoded is '%20'.
The following examples are for User object calls.
Resource field 'firstName' matches regular expression '.Joe.':
firstName = ".*Joe.*"
To include this in a REST API call, the syntax would be:
Resource subfield 'settings.G2M.chatEnabled' matches regular expression 'true' or field 'admin' matches regular expression 'true':
settings.G2M.chatEnabled ="true"| admin ="true"
Resource field 'admin' matches 'true' and 'firstName' matches '[a-z]' or 'admin' matches 'false' and 'lastName' not matches '[a-z]':
(admin ="true"& firstName = "[a-z]+") | (admin ="false" & lastName != "[a-z]+")
Resource field 'groupKey' matches regular expression '123':
groupKey = "123"
To sort REST call results, use the 'ascending' request parameter with a url-encoded comma-separated list of key-value pairs. Each pair defines the ascending preference for a resource field. The order of the pairs controls the order in which sorting is applied. The equal '=' character url-encoded is '%3D' and the comma character ',' url-encoded is '%2C'. Any resource field can be referenced in a sorting expression. Resource fields are case-sensitive. Non-existent resource fields are evaluated as null. The sort is formatted as follows:
To include this in a REST API call, the syntax would be:
Sort Comparisons Table
|Boolean||False < True|
|Array||Short array < long array, if lengths are equal compare sorted items|
|Null||Null < Non-null|
In order to request multiple pages, you will have to make multiple calls with different offset values. The client defines what a page means by providing a constant pageSize parameter. Coming back to my example with 50 users in an account. The client defines that one “page” contains 20 users and can then request one page after the other till it retrieved all users or just doesn’t use the parameters at all.
Pagination sets a specific page or interval of resources during bulk queries. The 'offset' and 'pageSize' request parameters can be used to perform pagination in REST calls. The 'offset' request parameter is the zero-based starting position of the page. The offset must be non-negative. If it goes beyond the bounds of the queried list, it will automatically be truncated to the index of the last item. The default offset is 0. The 'pageSize' request parameter determines the max length of thepage. It must be positive. If it goes beyond the bounds of the queried list given the offset, it will automatically be truncated to include all of the items beginning at the offset. The default offset is 1.
For example, the array [1, 2, 3] can be divided into the following pages: , [1, 2], [1, 2, 3], , [2, 3], and . The pages have different offsets and page sizes.  has offset 0 and size 1. [2, 3] has offset 1 and page size 2.  has offset 2 and page size 1.
Example Request Parameters:
The following is an example of the parameters syntax in a call (in curl format) using the search terms firstName = Janis, and lastName = Gould. The search terms are added following the ?:
curl -X GET \ https://api.getgo.com/admin/rest/v1/users?pageSize=10&offset=10&filter=(lastName="(?i).*Gould.*")&ascending=firstName=true \ -H 'Accept: application/json' \ -H 'Content-type: application/json' \ -H 'Authorization: OAuth oauth_token= ZlUe11FakEyCWxtOkeN3wk0uTKuL'
The suppressEmail Boolean can be used as a parameter on selected calls to add, update or delete user licenses. The syntax is:
curl -X DELETE \ https://api.getgo.com/admin/rest/v1/licenses/123,456/groups/123,456,789/users?suppressEmail= “true” \ -H 'Accept: application/json' \ -H 'Content-type: application/json' \ -H 'Authorization: OAuth oauth_token= ZlUe11FakEyCWxtOkeN3wk0uTKuL'
Converting JSON Response to Excel Format
This method returns data in a JSON payload by default, but can be modified to return the data in spreadsheet (XSLX) format. To do this use the following syntax on the request:
curl -X GET \ https://api.getgo.com/admin/rest/v1/users/123/meeting/history?_accept=application%2Fvnd.openxmlformats-officedocument.spreadsheetml.sheet&_authorization=9120477882223403267dca61zBW2wT9rVFzixze4oQGLC5l0of&fromDate=1402297200000&toDate=1404975599000 \ -H 'Accept: application/json' \ -H 'Content-type: application/json' \ -H 'Authorization: OAuth oauth_token= ZlUe11FakEyCWxtOkeN3wk0uTKuL'