Public/New-AtwsAttachment.ps1

#Requires -Version 4.0

<#
 
.COPYRIGHT
Copyright (c) Office Center Hønefoss AS. All rights reserved. Based on code from Jan Egil Ring (Crayon). Licensed under the MIT license.
See https://github.com/officecenter/Autotask/blob/master/LICENSE.md for license information.
 
#>

Function New-AtwsAttachment {


  <#
      .SYNOPSIS
      This function creates a new attachment through the Autotask Web Services API.
      .DESCRIPTION
      This function creates a new attachment connected to either an Account, an Opportunity,
      a Project or a Ticket. The attachment can be passed through the pipeline or provided as
      en URL or a file or folder path.
      .INPUTS
      Nothing
      .OUTPUTS
      Autotask attachments
      .EXAMPLE
      New-AtwsAttachment -TicketId 0 -Path C:\Document.docx
      Uploads C:\Document.docx as an attachment to the Ticket with id 0 and sets the attachment title to 'Document.docx'.
      .EXAMPLE
      New-AtwsAttachment -TicketId 0 -Path C:\Document.docx -Title 'A title'
      Uploads C:\Document.docx as an attachment to the Ticket with id 0 and sets the attachment title to 'A title'.
      .EXAMPLE
      New-AtwsAttachment -TicketId 0 -Path C:\Document.docx -FileLink
      Adds an file link attachment to the Ticket with id 0, title 'Document.docx' and C:\Document.docx as full path.
      .EXAMPLE
      $Attachment = Get-AtwsAttachment -TicketID 0 | Select-Object -First 1
      New-AtwsAttachment -Data $Attachment.Data -TicketId 1 -Title $Attachment.Info.Title -Extension $([IO.Path]::GetExtension($Attachment.Info.FullPath))
      Gets the first attachment from Ticket with id 0 and attaches it to Ticket with id 1
      .NOTE
      Strongly related to Get-AtwsAttachmentInfo
  #>


  [CmdLetBinding(SupportsShouldProcess = $true, DefaultParameterSetName = 'Ticket', ConfirmImpact = 'None')]
  Param
  (

    # An object as a byte array that will be attached to an Autotask object
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Account_as_byte'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Opportunity_as_byte'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Project_as_byte'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Ticket_as_byte'
    )]
    [ValidateNotNullOrEmpty()]
    [Byte[]]
    $Data,
    
    # An object as a byte array that will be attached to an Autotask object
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Account_as_byte'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Opportunity_as_byte'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Project_as_byte'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Ticket_as_byte'
    )]
    [ValidateNotNullOrEmpty()]
    [ValidatePattern('^\.?\w+$')]
    [string]
    $Extension,

    # A is required for Data
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Account_as_byte'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Opportunity_as_byte'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Project_as_byte'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Ticket_as_byte'
    )]
    [Parameter(
        ParameterSetName = 'Account'
    )]
    [Parameter(
        ParameterSetName = 'Opportunity'
    )]
    [Parameter(
        ParameterSetName = 'Project'
    )]
    [Parameter(
        ParameterSetName = 'Ticket'
    )]
    [Parameter(
        ParameterSetName = 'Account_as_url'
    )]
    [Parameter(
        ParameterSetName = 'Opportunity_as_url'
    )]
    [Parameter(
        ParameterSetName = 'Project_as_url'
    )]
    [Parameter(
        ParameterSetName = 'Ticket_as_url'
    )]
    [ValidateNotNullOrEmpty()]
    [string]
    $Title,
    
    # A file path that will be attached to an Autotask object
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Account'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Opportunity'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Project'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Ticket'
    )]
    [ValidateNotNullOrEmpty()]
    [ValidateScript({
          if( -Not ($_ | Test-Path) ){
            throw "File or folder does not exist"
          }
          return $true
    })]
    [IO.FileInfo]
    $Path,

    # URL to attach
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Account_as_url'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Opportunity_as_url'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Project_as_url'
    )]
    [Parameter(
        Mandatory = $true, 
        ParameterSetName = 'Ticket_as_url'
    )]
    [URI]
    $URI,
    
    # Attach as a file link, not an attachment
    [Parameter(
        ParameterSetName = 'Account_as_url'
    )]
    [Parameter(
        ParameterSetName = 'Opportunity_as_url'
    )]
    [Parameter(
        ParameterSetName = 'Project_as_url'
    )]
    [Parameter(
        ParameterSetName = 'Ticket_as_url'
    )]
    [Alias('Link')]
    [switch]
    $FileLink,
    
    # Attach as a folder link, not an attachment
    [Parameter(
        ParameterSetName = 'Account_as_url'
    )]
    [Parameter(
        ParameterSetName = 'Opportunity_as_url'
    )]
    [Parameter(
        ParameterSetName = 'Project_as_url'
    )]
    [Parameter(
        ParameterSetName = 'Ticket_as_url'
    )]
    [Alias('Folder')]
    [switch]
    $FolderLink,

    # Account ID
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Account'
    )]
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Account_as_byte'
    )]
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Account_as_url'
    )]
    [ValidateScript({
          if( -Not (Get-AtwsAccount -id $_) ){
            throw "Account does not exist"
          }
          return $true
    })]    
    [long]
    $AccountID,

    # Opportunity ID
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Opportunity'
    )]
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Opportunity_as_byte'
    )]
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Opportunity_as_url'
    )]
    [ValidateScript({
          if( -Not (Get-AtwsOpportunity -id $_) ){
            throw "Opportunity does not exist"
          }
          return $true
    })]
    [long]
    $OpportunityID,

    # Project ID
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Project'
    )]
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Project_as_byte'
    )]
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Project_as_url'
    )]
    [ValidateScript({
          if( -Not (Get-AtwsProject -id $_) ){
            throw "Project does not exist"
          }
          return $true
    })]
    [long]
    $ProjectID,

    # Ticket ID
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Ticket'
    )]
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Ticket_as_byte'
    )]
    [Parameter(
        Mandatory = $true,
        ParameterSetName = 'Ticket_as_url'
    )]
    [ValidateScript({
          if( -Not (Get-AtwsTicket -id $_) ){
            throw "Ticket does not exist"
          }
          return $true
    })]
    [long]
    $TicketID,

    [ValidateSet('All Autotask Users','Internal Users Only')]
    [string]
    $Publish = 'All Autotask Users'
   
  )

  begin { 
   
    # Enable modern -Debug behavior
    if ($PSCmdlet.MyInvocation.BoundParameters['Debug'].IsPresent) { $DebugPreference = 'Continue' }
    
    Write-Debug ('{0}: Begin of function' -F $MyInvocation.MyCommand.Name)
    
    # Dynamic field info
    $fields = Get-AtwsFieldInfo -Entity AttachmentInfo
    $DateTimeParams = $fields.Where({$_.Type -eq 'datetime'}).Name
    $Picklists = $fields.Where{$_.IsPickList}
    
    # Set up TimeZone offset handling
    if (-not($script:ESTzone)) {
      $script:ESTzone = [System.TimeZoneInfo]::FindSystemTimeZoneById("Eastern Standard Time")
    }
    
    if (-not($script:ESToffset)) {
      $now = Get-Date
      $ESTtime = [System.TimeZoneInfo]::ConvertTimeFromUtc($now.ToUniversalTime(), $ESTzone)

      $script:ESToffset = (New-TimeSpan -Start $ESTtime -End $now).TotalHours
    }
    
    # Publish dictionary
    $PublishToIndex = @{
      'All Autotask Users' = '1'
      'Internal Users Only' = '2'
    }
  }


  process {
    
    # A new Attachment object
    $Attachment = New-object "Autotask.Attachment"
    
    # A new AttachmentInfo object
    $AttachmentInfo = New-object "Autotask.AttachmentInfo"
    
    # Attach info object to attachment object
    $Attachment.Info = $AttachmentInfo

    # Publishsettings
    $AttachmentInfo.Publish = $PublishToIndex[$Publish]
    
    # Attachment type
    if ($Data) {
      $Attachment.Data = $Data
      $AttachmentInfo.Type = 'FILE_ATTACHMENT'
      $AttachmentInfo.FullPath = '{0}.{1}' -F $Title, $Extension.TrimStart('.')
    }
    # Is it an URL?
    elseif ($URI) {
      if ($FolderLink.IsPresent) {
        $AttachmentInfo.Type = 'FOLDER_LINK'
      }
      elseif ($FileLink.IsPresent) {
        $AttachmentInfo.Type = 'FILE_LINK'
      }
      else { 
        $AttachmentInfo.Type = 'URL'
      }
      $ATtachmentInfo.FullPath = $URI.AbsoluteUri
      $AttachmentInfo.Title = $AttachmentInfo.FullPath
    }
    # It is a file and it is going to be attached.
    else {
      [Byte[]]$Data = Get-Content -Path $Path.FullName -Encoding Byte -ReadCount 0
      $Attachment.Data = $Data

      # Type is attachment
      $AttachmentInfo.Type = 'FILE_ATTACHMENT'
      $AttachmentInfo.Title = $Path.BaseName
      $AttachmentInfo.FullPath = $Path.FullName
      
      # Determine content type by file name
      Add-Type -AssemblyName "System.Web"
      $AttachmentInfo.ContentType = [System.Web.MimeMapping]::GetMimeMapping($Path.FullName)

    }
    
    # Overwrite title with $Title if it exists
    if ($Title) {
      $AttachmentInfo.Title = $Title
    }
    
    # What are we attaching to?
    $objectType = ($PSCmdlet.ParameterSetName -split '_')[0]
  
    $AttachmentInfo.ParentId = $TicketId + $AccountID + $ProjectID + $OpportunityId
    $AttachmentInfo.ParentType = $Picklists.Where{$_.name -eq 'ParentType'}.PickListValues.Where{$_.Label -eq $objectType}.Value

    # Prepare ShouldProcess
    $caption = $MyInvocation.MyCommand.Name
    $verboseDescription = '{0}: About to create an attachment of type {1} with title {2}.' -F $caption, $AttachmentInfo.Type, $AttachmentInfo.Title
    $verboseWarning = '{0}: About to create an attachment of type {1} with title {2}. Do you want to continue?' -F $caption, $AttachmentInfo.Type, $AttachmentInfo.Title
    
    # Do it, I dare you!
    if ($PSCmdlet.ShouldProcess($verboseDescription, $verboseWarning, $caption)) { 
      $AttachmentId = $Script:Atws.CreateAttachment($Attachment)
      
      $result = Get-AtwsAttachmentInfo -id $AttachmentId
      
      Write-Verbose ('{0}: Created attachment with id {1} and title {2}' -F $MyInvocation.MyCommand.Name, $AttachmentId, $result.Title)
    
    }
  }

  end {
    Write-Debug ('{0}: End of function' -F $MyInvocation.MyCommand.Name)
    if ($result) {
      Return $result
    }
  }


}