Versions Compared

Old Version 19

changes.mady.by.user Carlos Contreras

Saved on

compared with

New Version Current

changes.mady.by.user Paul Scott

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Scripting_function


Panel
titleDescription

Executes and distributes a report. Similar to scheduling a report to execute, except a schedule in is not required to utilize this function. This is a great way to distribute the report on demand from a client.

Note

The function system.report.executeAndDistribute() does not run on its own thread and can get blocked. For example, if a printer is backed up and it takes a while to finish the request made by this function, the script will block the execution of other things on that thread until it finishes. Be sure to keep this in mind when using it in a script.

Panel
titleClient Permission Restrictions

This scripting function has no Client Permission restrictions.

Panel
titleSyntax
Info

This function accepts keyword arguments.

system.report.executeAndDistribute(path, project, [parameters], action, [actionSettings])

  • Parameters

String path - The path to the existing report.

String project - The name of the project where the report is located. Optional in client scope. Optional in session scope as of 8.0.5.

PyDictionary parameters - An optional dictionary of parameter overrides, in the form name:value pairs.

String action - The name of the distribution action to use. The action parameter supports the following keys as strings: 

      • email
      • print
      • save
      • ftp

PyDictionary actionSettings - An optional dictionary of settings particular to the action. Missing values will use the default value for that action.

  • Returns

None

  • Throws

IllegalArgumentException - Thrown when any of the following occurs: If the file type is not recognized, path does not exist, project does not exist, or a key is not valid.

  • Scope

Gateway, Vision Client, Perspective Session

Panel
titleValues for actionSettings

The action settings parameter supports an optional dictionary of settings particular to the action. Missing values will use the default value for that action.

Info

The email action now has the ability to add emails to the reply to field of the email. The replyTo, replyToRoles, and replyToUserSource keys have been added to the possible dictionay options.

  • email 
    • Setting Keys: "smtpServerName", "from", "subject", "body", "attachmentName", "retries", "fileType", "to", "cc", "bcc", "replyTo", "useRoles", "roles", "userSource", "replyToRoles", "replyToUserSource".
    • Note: To, cc, bcc, and replyTo must be Python lists. If useRoles is True, to, cc and bcc will be ignored and all email addresses for all users matching roles in userSource (which defaults to the project's current user source) will be in the to field. Similarly, all users matching the replyToRoles in replyToUserSource will be in the reply to field of the email. If useRoles is true but no roles are listed, all user email addresses in userSource will be in the to field. If omitted, fileType defaults to pdf.
  • print 
    • Setting Keys: "primaryPrinterName", "backupPrinterName", "copies", "printBothSides", "collate", "useRaster", "rasterDPI", "useAutoLandscape", "pageOrientation". 
    • Note: primaryPrinterName defaults to the default printer. backupPrinterName defaults to "none", but can also have the special value of "default". printBothSides, collate, and useRaster are booleans which default to false. rasterDPI is only used if useRaster is true. useAutoLandscape defaults to true. If useAutoLandscape is false, pageOrientation, which can have values of "portrait" or "landscape" (default is "portrait"), is used.
  • save 
    • Setting Keys: "path", "fileName" and "format". 
    • Note: Since the script is sent to the gateway for execution, path and fileName must be relative to the gateway.
  • ftp
    • Setting Keys: "server", "port", "username", "password", "useSSL", "path", "fileName", and "format". 
    • Note: Server and fileName are required. If omitted, fileType defaults to pdf, port defaults to 21, and useSSL defaults to false.
Panel
titleValues for filetype and format

The following is a list of values for the actionSettings filetype and format keys.

  • pdf
  • html
  • csv
  • rtf
  • jpeg
  • png
  • xml
New_in
Version8.0.4


The following values for filetype were added in 8.0.4:

  • xls
  • xlsx
Panel
titleCode Examples
Code Block
languagepy
titleCode Snippet - Emailing a Report
# Executes and distributes the report to an email address.
system.report.executeAndDistribute(path="My Report Path", project="My Project", action= "email", 
  actionSettings = {"to":["plantmanager@myplant.com"], "smtpServerName":"myplantMailServer", "from":"reporting@myplant.com", "subject":"Production Report"})
Panel
Code Block
languagepy
titleCode Snippet - Emailing a Report
# Executes and distributes the report to all users in the default user source who are Supervisors or Managers.
system.report.executeAndDistribute(path="My Report Path", project="My Project", action= "email", 
  actionSettings = {"useRoles":True, "roles":["Supervisor", "Manager"], "smtpServerName":"myplantMailServer", "from":"reporting@myplant.com", "subject":"Production Report"})
Panel
Code Block
languagepy
titleCode Snippet - Sending Report to FTP Server
# Executes and distributes the report to an ftp server with parameter values passed into the report
reportParameters = {"StartDate":system.date.addHours(system.date.now(), -12), "EndDate":system.date.now()}
settings = {"server":"10.20.1.80", "port":22, "username":"Ignition", "password":"Secret", "useSSL": False, "path":"C:\\FTP", "fileName":"Ignition Report", "format":"pdf"}
system.report.executeAndDistribute(path="My Report Path", project="My Project", parameters=reportParameters, action= "ftp", actionSettings = settings)
Panel
Code Block
languagepy
titleCode Snippet - Saving Report
# Executes and distributes the report to save a PDF
settings = {"path":"C:\\Ignition Reports", "fileName":"Report.pdf", "format":"pdf"}
system.report.executeAndDistribute(path="My Report Path", project="My Project", action="save", actionSettings=settings)
Panel
titleKeywords

system report executeAndDistribute, report.executeAndDistribute