Manage Destinations and Output Settings

Choose where ATRS delivers your report and which output format it generates. A single-report schedule can use email, a disk folder or both.

For a package, include its destinations in the complete package definition. Follow Create and Manage Report Packages; the SingleSchedule destination operations below apply to single-report schedules.

Before you begin

Complete Authentication and Token Management. The PowerShell examples use $AtrsBaseUrl and $AtrsHeaders from that guide. Run the steps in order in the same PowerShell session. Use your installation’s address and identifiers in place of the examples.

For full schedule edits, use the disabled test copy and saved intended definition from Create a Schedule from a Working Template. Confirm test recipients and server-side write permissions before running a report.

Choose a destination and output format

Set OutputFormat to the exact label supported by the Tableau workflow. The PDF example uses Acrobat Format (*.pdf). Test other formats with the intended report before exposing them in an application.

Changing a filename extension does not convert file contents.

1. Read the current destinations

Use GET /api/SingleSchedule/Get with the schedule ID. Inspect EmailDestinations and DiskDestinations and record their DestinationId values.

Keep the full intended definition separately. A saved response can omit settings required for a later full update.

2. Add an email destination

Use POST /api/SingleSchedule/AddEmailDestination for the disabled test copy. $AtrsNewId comes from the template workflow. Replace the test address before sending:

$AtrsEmail = @{
    ParentId=$AtrsNewId; DestinationName="API test email"; DestinationType="Email"
    OutputFormat="Acrobat Format (*.pdf)"; Enabled=$true
    To=@("[email protected]"); Cc=@(); Bcc=@()
    Subject="ATRS controlled test"; Body="Controlled test output"; BodyFormat="TEXT"
} | ConvertTo-Json -Depth 10
$AtrsNewEmail = Invoke-RestMethod -Method Post `
    -Uri "$AtrsBaseUrl/api/SingleSchedule/AddEmailDestination?clearExisting=false" `
    -Headers $AtrsHeaders -ContentType "application/json" -Body $AtrsEmail -TimeoutSec 30
$AtrsNewEmail | ConvertTo-Json -Depth 20

ParentId identifies the report schedule. Save the returned destination ID and retrieve the parent schedule again to confirm its recipients, subject, body and output format:

$AtrsSaved = Invoke-RestMethod -Method Get `
    -Uri "$AtrsBaseUrl/api/SingleSchedule/Get?Id=$AtrsNewId" -Headers $AtrsHeaders -TimeoutSec 30
$AtrsSaved.EmailDestinations | ConvertTo-Json -Depth 30
$AtrsDestinationId = [long]$AtrsNewEmail.DestinationId
if ($AtrsDestinationId -le 0) { throw "Inspect saved destinations before another write" }
$AtrsEmailObject = $AtrsEmail | ConvertFrom-Json
$AtrsEmailObject | Add-Member -NotePropertyName DestinationId -NotePropertyValue $AtrsDestinationId -Force
$AtrsDefinition.EmailDestinations = @($AtrsDefinition.EmailDestinations | Where-Object { $null -ne $_ }) + @($AtrsEmailObject)
$AtrsDefinition | ConvertTo-Json -Depth 100 | Set-Content -LiteralPath $AtrsDefinitionPath -Encoding UTF8

This incorporates the intended new destination and its assigned ID into the retained definition. Compare it with saved state before changing the subject or other fields.

clearExisting=false keeps existing email destinations. clearExisting=true deletes them before adding the replacement; disk destinations remain. Use replacement only when all current email destinations should be removed, because insertion failure does not promise restoration.

3. Change an existing destination

Use the full intended definition from the template workflow and POST /api/SingleSchedule/Update. Keep every destination that should remain and preserve its DestinationId.

For example, to change one email subject on the disabled copy:

$AtrsDestinationId = [long](Read-Host "Email DestinationId on the test copy")
$AtrsEmail = @($AtrsDefinition.EmailDestinations | Where-Object { $_.DestinationId -eq $AtrsDestinationId })
if ($AtrsEmail.Count -ne 1) { throw "Select one destination in the retained definition" }
$AtrsEmail[0].Subject = Read-Host "New subject"
$AtrsDefinition.Schedule.Enabled = $false
$AtrsDefinition | ConvertTo-Json -Depth 100 | Set-Content -LiteralPath $AtrsDefinitionPath -Encoding UTF8
Invoke-RestMethod -Method Post -Uri "$AtrsBaseUrl/api/SingleSchedule/Update" `
    -Headers $AtrsHeaders -ContentType "application/json" `
    -Body ($AtrsDefinition | ConvertTo-Json -Depth 100) -TimeoutSec 60
$AtrsSaved = Invoke-RestMethod -Method Get `
    -Uri "$AtrsBaseUrl/api/SingleSchedule/Get?Id=$AtrsNewId" -Headers $AtrsHeaders -TimeoutSec 30
$AtrsSaved.EmailDestinations | ConvertTo-Json -Depth 30

If you added an email through the dedicated add operation, first incorporate its saved object and identifier into the intended definition. Confirm its full settings before the update.

The dedicated selective email update/delete routes are not prerequisites for this workflow. Use the full update described here; confirm availability with Support before building an integration around a selective route.

4. Configure a disk destination

A disk destination belongs in the full definition’s DiskDestinations array. This is one destination object, not a complete request:

{
  "DestinationName": "Test PDF folder",
  "DestinationId": 0,
  "DestinationType": "Disk",
  "OutputFormat": "Acrobat Format (*.pdf)",
  "CustomOutputFileName": "",
  "CustomOutputExtension": "",
  "Enabled": true,
  "OutputPath": "C:\\ATRS-Test"
}

Use 0 for a new destination and the existing ID for one you retain. Replace the example path with a real folder on the execution server. Check filesystem and share permissions for the execution account.

5. Preserve complete collections

On a full update:

• Send both destination arrays as non-null collections.
• Include every destination that should remain, with its ID and settings.
• Use [] only for a collection you intend to leave empty.
• Retain at least one valid delivery destination for this single-schedule workflow.

Removing an entry from the intended collection removes it during the full update. Verify the saved collections afterward. This does not recall mail or files already delivered.

For email, send To, Cc and Bcc as address arrays. Set BodyFormat to TEXT or HTML and serialize message content with a JSON serializer. The sender-address field is spelled CustomerSenderAddress; the mail system must permit that sender.

6. Verify delivery

Read the schedule independently, inspect all retained destinations, then run the Quick Start. Check the actual email or file, its format and its contents. Saving destination settings does not execute the report.

Troubleshooting