Public/Agents/New-FreshServiceAgent.ps1
|
<#
.SYNOPSIS Creates a new Freshservice Agent. .DESCRIPTION Creates a new Freshservice Agent via REST API. https://api.freshservice.com/#create_an_agent .PARAMETER first_name First name of the agent. .PARAMETER last_name Last name of the agent. .PARAMETER occasional True if the agent is an occasional agent, and false if full-time agent. .PARAMETER job_title Job title of the agent. .PARAMETER email Email address of the agent. .PARAMETER work_phone_number Work phone number of the agent. .PARAMETER mobile_phone_number Mobile phone number of the agent. .PARAMETER department_ids Unique IDs of the departments associated with the agent. .PARAMETER can_see_all_tickets_from_associated_departments Set to true if the agent must be allowed to view tickets filed by other members of the department, and false otherwise. .PARAMETER reporting_manager_id User ID of the agent's reporting manager. .PARAMETER address Address of the agent. .PARAMETER time_zone Time zone of the agent. .PARAMETER time_format Time format for the agent. Possible values: 12h (12 hour format) 24h (24 hour format) .PARAMETER language Language used by the agent. The default language is "en" (English). .PARAMETER location_id Unique ID of the location associated with the agent. .PARAMETER background_information Background information of the agent. .PARAMETER scoreboard_level_id Unique ID of the level of the agent in the Arcade. Possible values:--1 (Beginner)--2 (Intermediate)--3 (Professional)--4 (Expert)--5 (Master)--6 (Guru) .PARAMETER member_of Unique IDs of the groups that the agent is a member of. The response value for this field would only contain the list of groups that the agent is an approved member of. The member_of_pending_approval read-only attribute in the response will include the list of groups for which the agent's member access is pending approval by a group leader. .PARAMETER observer_of Unique IDs of the groups that the agent is an observer of. The response value for this field would only contain the list of groups that the agent is an approved observer of. The observer_of_pending_approval read-only attribute in the response will include the list of groups for which the agent's observer access is pending approval by a group leader. .PARAMETER roles Each individual role is a hash in the roles array that contains the attributes.role_id: Unique ID of the role assigned"assignment_scope: The scope in which the agent can use the permissions granted by this role. Possible values include entire_helpdesk (all plans) .PARAMETER license_type The type of license, IT or Business. .PARAMETER signature Signature of the agent in HTML format. .PARAMETER custom_fields Key-value pair containing the names and values of the (custom) agent fields. .PARAMETER workspace_ids Workspace Ids the agent will be a member of. .EXAMPLE $newFreshServiceAgentRoleConfigSplat1 = @{ role_id = 21000150301 #IT Ops Agent - Get-FreshServiceAgentRole assignment_scope = 'specified_groups' groups = 21000188388,21000188389 #Incident Team and Major Incident Team- Get-FreshServiceAgentGroup } $newFreshServiceAgentRoleConfigSplat2 = @{ role_id = 21000150294 #SD Supervisor - Get-FreshServiceAgentRole assignment_scope = 'specified_groups' groups = 21000188403 #Helpdesk Monitoring Team - Get-FreshServiceAgentGroup } $agentRoles = foreach ($splat in @($newFreshServiceAgentRoleConfigSplat1, $newFreshServiceAgentRoleConfigSplat2)) { New-FreshServiceAgentRoleConfig @splat } $newFreshServiceAgentSplat = @{ first_name = 'Ralph' last_name = 'smith' job_title = 'Code Monkey' email = 'Alex.agent@example.com' background_information = 'Awesome helpdesk training' roles = $agentRoles } New-FreshServiceAgent @newFreshServiceAgentSplat active : True address : auto_assign_status_changed_at : auto_assign_tickets : True background_information : Awesome helpdesk training can_see_all_tickets_from_associated_departments : False created_at : 3/27/2023 5:10:31 PM custom_fields : @{employee_id=} department_ids : {} department_names : email : Alex.agent2@example.com external_id : first_name : Ralph has_logged_in : False id : 21001941828 job_title : Code Monkey language : en last_active_at : last_login_at : last_name : Smith location_id : location_name : mobile_phone_number : occasional : False reporting_manager_id : role_ids : {21000150301, 21000150294} roles : {@{role_id=21000150294; assignment_scope=specified_groups; groups=System.Object[]}, @{role_id=21000150301; assignment_scope=specified_groups; groups=System.Object[]}} scopes : @{ticket=; problem=; change=; asset=; solution=; contract=} scoreboard_level_id : 1 scoreboard_points : signature : time_format : 12h time_zone : Eastern Time (US & Canada) updated_at : 3/27/2023 5:10:31 PM vip_user : False work_phone_number : group_ids : {} member_of : {} observer_of : {} member_of_pending_approval : {} observer_of_pending_approval : {} Adds a new Freshservice Agent. There is a helper function New-FreshServiceAgentRoleConfig to assist with creating roles based on the documentation format, which generates a PSObject. Note there are dependent ids that can be obtained from other cmdlets (e.g. Get-FreshServiceAgentRole and Get-FreshServiceAgentGroup) Multiple roles can be mapped to a single Agent. .NOTES This module was developed and tested with Freshservice REST API v2. #> function New-FreshServiceAgent { [CmdletBinding(SupportsShouldProcess=$true, ConfirmImpact='Medium')] param ( [Parameter( Mandatory = $true, HelpMessage = 'First name of the agent.', ValueFromPipelineByPropertyName = $true )] [Alias('FirstName')] [string]$first_name, [Parameter( Mandatory = $false, HelpMessage = 'Last name of the agent.', ValueFromPipelineByPropertyName = $true )] [Alias('LastName')] [string]$last_name, [Parameter( Mandatory = $false, HelpMessage = 'True if the agent is an occasional agent, and false if full-time agent.', ValueFromPipelineByPropertyName = $true )] [boolean]$occasional, [Parameter( Mandatory = $false, HelpMessage = 'Job title of the agent.', ValueFromPipelineByPropertyName = $true )] [Alias('JobTitle')] [string]$job_title, [Parameter( Mandatory = $true, HelpMessage = 'Email address of the agent.', ValueFromPipelineByPropertyName = $true )] [string]$email, [Parameter( Mandatory = $false, HelpMessage = 'Work phone number of the agent.', ValueFromPipelineByPropertyName = $true )] [Alias('WorkNumber','WorkPhoneNumber')] [string]$work_phone_number, [Parameter( Mandatory = $false, HelpMessage = 'Mobile phone number of the agent.', ValueFromPipelineByPropertyName = $true )] [Alias('MobilePhone','MobilePhoneNumber')] [string]$mobile_phone_number, [Parameter( Mandatory = $false, HelpMessage = 'Unique IDs of the departments associated with the agent', ValueFromPipelineByPropertyName = $true )] [Alias('DepartmentId')] [long[]]$department_ids, [Parameter( Mandatory = $false, HelpMessage = 'Set to true if the agent must be allowed to view tickets filed by other members of the department, and false otherwise', ValueFromPipelineByPropertyName = $true )] [boolean]$can_see_all_tickets_from_associated_departments, [Parameter( Mandatory = $false, HelpMessage = 'User ID of the agents reporting manager.', ValueFromPipelineByPropertyName = $true )] [Alias('ReportingManagerId')] [long]$reporting_manager_id, [Parameter( Mandatory = $false, HelpMessage = 'Address of the agent.', ValueFromPipelineByPropertyName = $true )] [string]$address, [Parameter( Mandatory = $false, HelpMessage = 'Time zone of the agent.', ValueFromPipelineByPropertyName = $true )] [Alias('TimeZone')] [string]$time_zone, [Parameter( Mandatory = $false, HelpMessage = 'Time format for the agent.Possible values: --12h (12 hour format) --24h (24 hour format)', ValueFromPipelineByPropertyName = $true )] [ValidateSet('12h','24h')] [Alias('TimeFormat')] [string]$time_format, [Parameter( Mandatory = $false, HelpMessage = 'Language used by the agent. The default language is "en" (English). Read more here.', ValueFromPipelineByPropertyName = $true )] [string]$language, [Parameter( Mandatory = $false, HelpMessage = 'Unique ID of the location associated with the agent.', ValueFromPipelineByPropertyName = $true )] [Alias('LocationId')] [long]$location_id, [Parameter( Mandatory = $false, HelpMessage = 'Background information of the agent.', ValueFromPipelineByPropertyName = $true )] [Alias('BackgroundInformation')] [string]$background_information, [Parameter( Mandatory = $false, HelpMessage = 'Unique ID of the level of the agent in the Arcade. Possible values:--1 (Beginner)--2 (Intermediate)--3 (Professional)--4 (Expert)--5 (Master)--6 (Guru)', ValueFromPipelineByPropertyName = $true )] [ValidateRange(1,6)] [Alias('ScoreboardLevel')] [int]$scoreboard_level_id, [Parameter( Mandatory = $false, HelpMessage = 'Unique IDs of the groups that the agent is a member of. The response value for this field would only contain the list of groups that the agent is an approved member of. The member_of_pending_approval read-only attribute in the response will include the list of groups for which the agents member access is pending approval by a group leader.', ValueFromPipelineByPropertyName = $true )] [Alias('MemberOf')] [long[]]$member_of, [Parameter( Mandatory = $false, HelpMessage = 'Unique IDs of the groups that the agent is an observer of. The response value for this field would only contain the list of groups that the agent is an approved observer of. The observer_of_pending_approval read-only attribute in the response will include the list of groups for which the agents observer access is pending approval by a group leader.', ValueFromPipelineByPropertyName = $true )] [Alias('ObserverOf')] [long[]]$observer_of, [Parameter( Mandatory = $true, HelpMessage = 'Each individual role is a hash in the roles array that contains the attributes.role_id: Unique ID of the role assigned"assignment_scope: The scope in which the agent can use the permissions granted by this role. Possible values include entire_helpdesk (all plans)', ValueFromPipelineByPropertyName = $true )] [object[]]$roles, [Parameter( Mandatory = $false, HelpMessage = 'Signature of the agent in HTML format.', ValueFromPipelineByPropertyName = $true )] [ValidateSet('it','business')] [string]$license_type, [Parameter( Mandatory = $false, HelpMessage = 'Signature of the agent in HTML format.', ValueFromPipelineByPropertyName = $true )] [string]$signature, [Parameter( Mandatory = $false, HelpMessage = 'Key-value pair containing the names and values of the (custom) agent fields.', ValueFromPipelineByPropertyName = $true )] [Alias('CustomFields')] [hashtable]$custom_fields, [Parameter( Mandatory = $false, HelpMessage = 'Workspace Ids', ValueFromPipelineByPropertyName = $true )] [int[]]$workspace_ids ) begin { $PrivateData = $MyInvocation.MyCommand.Module.PrivateData if (!$PrivateData.FreshserviceBaseUri) { throw "No connection found! Setup a new Freshservice connection with New-FreshServiceConnection and then Connect-FreshService. Set a default connection with New-FreshServiceConnection or Set-FreshConnection to automatically connect when importing the module." } $uri = [System.UriBuilder]('{0}/agents' -f $PrivateData['FreshserviceBaseUri']) } process { $jsonBody = @{} $PSBoundParameters.keys.where{ $PSItem -notin $PrivateData.FreshserviceBodyExclusions }.foreach{ # switch ($PSItem) { # 'roles' { # #Force into array for JSON # $jsonBody[$PSItem.ToLower()] = @($PSBoundParameters[$PSItem]) # } # default { $jsonBody[$PSItem.ToLower()] = $PSBoundParameters[$PSItem] # } # } } try { if ($PSCmdlet.ShouldProcess($uri.Uri.AbsoluteUri)) { $params = @{ Uri = $uri.Uri.AbsoluteUri Method = 'POST' Body = $jsonBody | ConvertTo-Json -Depth 5 ErrorAction = 'Stop' } $result = Invoke-FreshworksRestMethod @params if ($result.Content) { $content = $result.Content | ConvertFrom-Json #API returns singluar or plural property based on the number of records, parse to get property returned. $objProperty = $content[0].PSObject.Properties.Name Write-Verbose -Message ("Returning {0} property with count {1}" -f $objProperty, $content."$($objProperty)".Count) $content."$($objProperty)" } } } catch { Throw $_ } } end {} } |