Using Filters and Parameters

What are filters and parameters?

When you run a command like Get-ITGlueUsers, you might want to see every user in your IT Glue account, or you might just want to get details about a specific user. In order to do that, you need to either filter your search, or add parameters that tell IT Glue's API what data to give you.

Sticking with Get-ITGlueUsers, the following parameters are supported:

    Get-ITGlueUsers [-filter_name <string>] [-filter_email <string>] [-filter_role_name {Administrator | Manager | Editor | Creator | Lite | Read-only}] [-sort {name | email | reputation | id | 
    created_at | updated-at | -name | -email | -reputation | -id | -created_at | -updated-at}] [-page_number <int>] [-page_size <int>] 

Let's look at each parameter in detail:

• -filter_name
  • This parameter lets us filter for an exact name. For example, let's say that "Jane Doe" is the name of one of our IT Glue users. Running Get-ITGlueUsers -filter_name "Jane Doe" would return the details regarding Jane Doe's account.
• -filter_email
  • This parameter lets you filter for an exact match on an email. Let's assume Jane Doe's email is [email protected]. Running Get-ITGlueUsers -filter_email "[email protected]" would also return Jane's account details.
• -filter_role_name
  • Want to only view user accounts with Administrator privileges? This is your parameter. Try Get-ITGlueUsers -filter_role_name "Administrator"
  • Notice how this parameter had multiple options. The supported roles in IT Glue that you can filter by are:
    • Administrator
    • Manager
    • Editor
    • Creator
    • Lite
    • Read-Only
• -sort
  • Sometimes pre-sorting the output IT Glue gives can save us time, especially when we only want to see what accounts were recently updated, or group output by alphabetical order. The -sort parameter lets you specify what to sort the output by.
  • Notice that there are options for this. You can sort by:
    • Name
    • Email
    • Reputation
    • ID
    • Created_at
    • Updated_at
  • You can inverse the sorting order by prefixing a dash [-] to any of the sort options, such as Get-ITGlueUsers -sort "-name", which will return users in reverse alphabetical order.
• -page_number
  • IT Glue outputs up to 50 results on a "page" by default. If you have 65 users, you will have to specify Get-ITGlueUsers -page_number "2" to view the latter 15 users.
• -page_size
  • What if you want to get the first 75 users without looking at multiple pages? Specifying the number of results on a given page allows you to do that. Try Get-ITGlueUsers -page_size "75"
  • ⚠️ Setting large values for -page_size could take a long time to load or go over the maximum size that a single request will allow. Please use this parameter with caution.

How do I make complex queries using multiple parameters?

The real power of parameters and filters comes from being able to make complex queries. Fortunately, that is easy! All you have to do is type one parameter after another when you call a function. For example, let's say that you want to return a list of the top 10 employees sorted by reputation that are set up with a Creator user role. That query combines a filter (user role), a sort (reputation), and a parameter (only the top 10). You could find that data by running Get-ITGlueUsers -filter_role_name "Creator" -sort "Reputation" -page_size "10". Try it out!

What parameters are supported?

You can find the parameters that any command offers by utilizing PowerShell's built in Get-Help <function name> cmdlet. For example, try running Get-Help Get-ITGlueUsers.

For a list of commands available with this module, run Get-Commands -module ITGlueAPI.

---

All parameters that IT Glue's API documentation makes available are respected. For more info on what these parameters are, check out http://api.itglue.com/developer