Skip to content

Latest commit

 

History

History
168 lines (124 loc) · 5.47 KB

README.MD

File metadata and controls

168 lines (124 loc) · 5.47 KB

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