Skip to content

DarkLite1/Toolbox.Cherwell

Repository files navigation

Description

A PowerShell module designed to easily interact with the Cherwell REST API. It provides CmdLet's for the most common CRUD operations like New-CherwellTicketHC, Get-CherwellTicketHC, Update-CherwellTicketHC, ... .

Examples

Create a new ticket

Using convenience arguments

Using the convenience arguments, the ones ending with *SamAccountName is the quickest way to create a new ticket. The module will try to find a single matching system user/customer automatically.

$ticketNr = New-CherwellTicketHC -Environment Stage -KeyValuePair @{
    IncidentType            = 'Incident'
    RequesterSamAccountName = 'cnorris'
    OwnedBySamAccountName   = 'bmarley'
    OwnedByTeam             = 'GLB'
    ShortDescription        = 'Server decommissioning'
    Description             = 'Decommission server'
    Priority                = '2'
    Source                  = 'Event'
    ServiceCountryCode      = 'BNL'
    Service                 = 'SERVER'
    Category                = 'Server lifecycle'
    SubCategory             = 'Submit Request'
}

Using Cherwell fields only

Using known Cherwell fields only allows more control in case of errors.

$systemUser = Get-CherwellSystemUserHC -Environment Stage -Filter @{
    FieldName  = 'EMail'
    Operator   = 'eq'
    FieldValue = '[email protected]'
} -PassThru

if ($systemUser.count -ne 1) { throw 'No user or multiple users found' }

$customer = Get-CherwellCustomerHC -Environment Stage -Filter @{
    FieldName  = 'SamAccountName'
    Operator   = 'eq'
    FieldValue = 'bmarley'
} -PassThru

if ($customer.count -ne 1) { throw 'No customer or multiple customers found' }

$ticketNr =  New-CherwellTicketHC -Environment Stage -KeyValuePair @{
    IncidentType            = 'Incident'
    CustomerRecID           = $customer.busObRecId
    OwnedByTeam             = 'GLB'
    OwnedBy                 = $systemUser.busObPublicId
    OwnedById               = $systemUser.busObRecId
    ShortDescription        = 'Server decommissioning'
    Description             = 'Decommission server'
    Priority                = '2'
    Source                  = 'Event'
    ServiceCountryCode      = 'BNL'
    Service                 = 'SERVER'
    Category                = 'Server lifecycle'
    SubCategory             = 'Submit Request'
}

Update a ticket

Close a ticket

To close a ticket the only thing required is to update the correct Cherwell ticket fields.

$systemUser = Get-CherwellSystemUserHC -Environment Test -Filter @{
    FieldName  = 'SamAccountName'
    Operator   = 'eq'
    FieldValue = 'cnorris'
} -PassThru

Update-CherwellTicketHC -Environment Test -Ticket 2020 -KeyValuePair @{
    OwnedBy          = $systemUser.busObPublicId
    OwnedById        = $systemUser.busObRecId
    OwnedByTeam      = 'BNL'
    Status           = 'Resolved'
    CloseDescription = 'We fixed it!'
}

Retrieve configuration items (CI)

Retrieve the CI types

As a first step you need to now which CI types are available in your Cherwell environment.

$allCiTypes =  Get-CherwellConfigItemTypeHC -Environment Stage

Retrieve all CI's of a specific type

Now that we know what the types are, let's retrieve all CI's for the first CI type.

Get-CherwellConfigItemHC -Environment Stage -Type $allCiTypes[0] -Verbose

Retrieve Cherwell Teams

Retrieve all teams that start with the value 'BNL' in the property 'Name'.

Get-CherwellTeamInfoHC -Environment Prod -Filter @{
    FieldName  = 'Name'
    Operator   = 'startswith'
    FieldValue = 'BNL'
}

Installation

Setup guide

  1. Clone the repository into the folder Toolbox.Cherwell
  2. Rename Passwords-example.json to Passwords.json and update the file with your environment details
  3. Optionally move the module folder to one of your module folders defined in $env:PSModulePath

Using the module

  • Run in any script Import-Module $modulePath and use the CmdLet's (only needed when the module is not in your default module folder $env:PSModulePath)
  • List all available CmdLet's Get-Command -Module Toolbox.Cherwell
  • Read the help Get-Help New-CherwellTicketHC
  • See the examples Get-Help New-CherwellTicketHC -Examples

Running tests

Add your config to the beginning of the file Toolbox.Cherwell.Tests.ps1 (overwrite the defaults as they will probably not work in our environment)

Install-Module -Name 'Pester'
Invoke-Pester $myPesterTestFile -Output 'Detailed'

Release notes version 3.5 (2020/10/08)

Updates

  • Made tests compliant with Pester 5
  • Added tests for invalid arguments within KeyValuePair
  • Improved parameter naming
    • all parameters within KeyValuePair are native Cherwell arguments except for the ones ending with *SamAccountName, these are custom convenience parameters where the SamAccountName is matched (by Get-CherwellSystemUserHC or Get-CherwellCustomerHC) with the correct user/customer within Cherwell:

      old name > new name > Cherwell matched field

    • SubmittedBy > SubmittedBySamAccountName > SubmitOnBehalfOfID

    • OwnedBy > OwnedBySamAccountName > OwnedByID and OwnedBy

    • Requester > RequesterSamAccountName > CustomerRecID

  • Added more examples

Breaking changes

  • KeyValuePair arguments
    • Renamed SubmittedBy, OwnedBy and Requester
    • When multiple users/customers are found for one of the *SamAccountName parameters an error is thrown instead of selecting the first random result

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published