Creating and Updating Objects

Creating and Updating Resources

Reading objects with Get-ITGlue<resourcename> commands are a great way to get familiar with the IT Glue PowerShell module, however the real power comes in being able to create and update the information inside your IT Glue account. This includes creating flexible assets, updating contacts, organizations, configuration items, and many other resources.

The IT Glue PowerShell Module takes a flexible approach, allowing you to create the data and parameters you want to send as a variable and then easily pass that to the module functions, which automatically take care of JSON conversion and everything else.

Creating Resources

Creating a resource is done by using the functions that start with the verb New-. For example, one would use the function New-ITGlueOrganizations -data <org_data> in order to create an organization. The first thing involved in creating a resource is formatting the data that will go into IT Glue. Let's represent that data in a variable called $data and create it using hash tables like the API documentation states.

data = @{
    type = 'organizations'
    attributes = @{
        name = '' #required
        description = ''
        organization_type_id = ''
        organization_status_id = ''
        quick_notes = ''
        alert = ''
        short_name = ''
    }
}

In the above code block, @{ ... } represents a hash table, which consists of key-value pairs. In this case, name is a key under the attributes hash. Fill out the values as you desire. Once you are done, it might look something like this:

data = @{
    type = 'organizations'
    attributes = @{
        name = 'Happy Frog' #required
        description = 'This is a description for Happy Frog'
        quick_notes = 'These are quick notes!'
        alert = 'Alert! This client operates 24/7, please schedule maintenance windows.'
        short_name = 'HAPPY'
    }
}

Once you have your $data variable finished, creating an organization is as easy as running:

New-ITGlueOrganizations -data $data

That's all there is to it! The output of that function actually gives you the organization id that was created as well. Try capturing the output by passing it into a variable like this: $output = New-ITGlueOrganizations -data $data.

Optional Parameters

Note that the organization_type_id and organization_status_id were omitted. For organizations, only the name field is required. The best reference for what is required is in the API documentation.

Those two fields were omitted specifically in order to single them out and explain a bit more about how the API works. Organization types (such as Vendor, Partner, Client) each have a unique id pertaining to them. You can find these by using the Get-ITGlueOrganizationTypes function.

Likewise, organization status represents things like (Active, Inactive, Off boarding, ...). These statuses can be found by digging in to Get-ITGlueOrganizationStatuses. Find the corresponding id for your desired organization type and status, and you can easily add them into the $data variable we created earlier.

Updating Resources

Creating documentation is one thing, but keeping it up to date has always been a problem that plagues MSPs. Now we can automate that by using the API to update resources in IT Glue! Let's look at how.

Updating an existing resource is much like creating one -- you fill out the desired values of the resource and pass it to the API using functions beginning with Set-, however in order to update an object that already exists, you have to know the id for that object. Remember how creating an organization returns the id of that organization? If we store that id, or otherwise find it, we can update that same org we just created. Let's first start by defining a variable to hold the desired values:

data = @{
    type = 'organizations'
    attributes = @{
        name = 'Happy Frog, Inc.'
        description = 'The description has changed'
        quick_notes = 'Concise quick notes will be updated via the API.'
    }
}

Note how we updated the name, description, and quick notes. By omitting the rest of the fields, they will remain unchanged. By combining the new data with the organization's id, we can update what is in IT Glue by running:

Set-ITGlueOrganizations -data $data -id <int> #put the org id returned earlier in place of <int>

The Set-ITGlueOrganizations function will take care of the rest!

Bulk Updating Resources

Updating objects one at a time is useful, however, sometimes it is advantageous to update things in bulk. Thankfully, functions like Set-ITGlueOrganizations can support this (based on supported API functionality - check the API documentation first). Let's update the alert field for two organizations, "Happy Frog, Inc." and "API Test Org". Our $data variable would look like this:

data = @(
    @{
        type = 'organizations'
        attributes = @{
            id = '' # Put the organization id for "Happy Frog, Inc." here
            alert = 'This alert was generated for Happy Frog via API bulk update.'
        }
    },
    @{
        type = 'organizations'
        attributes = @{
            id = '' # Put the organization id for "API Test Org" here
            alert = 'This alert was generated for API Test Org via API bulk update.'
        }
    }
)

Notice how instead of data = @{ ... } being present, there are parenthesis such that data = @( ... ). This is how PowerShell creates an array. Inside this array are two organization objects, each surrounded by @{ ... } so that they are represented by hashes.

Once you add however many organization objects you wish inside that array (separated by commas), you can update them all in one shot by running:

Set-ITGlueOrganizations -data $data

Note the omission of the -id parameter when calling the function. When making bulk updates, the API expects the organization id to be present as a key under the attributes hash table.

Beyond Organizations

Other forms of data in IT Glue can be created and updated in the same manner as organizations, you just have to make sure you have the right fields present in whatever you are passing to the PowerShell module functions. The API documentation has examples of what hashes and arrays are expected. Just remember that a hash table is created using @{ ... } in PowerShell, and an array is created by using @( ... ).

If you ever want to check to see if your data looks like the JSON shown in the API documentation, you can run ConvertTo-Json $data -Depth $ITGlue_JSON_Conversion_Depth, which will show the JSON equivalent to your PowerShell variable.