Actions - Developing Actions

For developers, Actions are a platform to build customized solutions for InFocus and support both SQL and Powershell. Below are a few examples of the kinds of solutions you could build using Actions.

Framework

Actions operate on a three-part framework that includes: Parameters, a Script and Return Types.

Parameters

Each Action collects a set of parameters which are then passed to the underlying Script. Parameters can be fed in programmatically (e.g. from InFocus) or sourced from end-user prompts.

Programmatic Parameters

For example, if running an action to suppress zero-hour timesheet rows when the timesheet it saved, InFocus will programmatically pass the following

Prompts

Prompts can be used to collect parameter inputs from the end-user. Displayed in a modal window, prompts are configured with the following properties:

Once a prompt has been completed by the end-user, the Action will pass the entered parameters to the Script for processing.

Passing Parameters

Regardless of how parameters are collected, they are passed to the script at execution. As such, the script will need to include syntax for receiving the parameters passed. For example,

Scripts

Scripts process the actual tasks of the Action. Supported query types include SQL and Powershell and are entered in the Query window via Custom Reports (UT>Custom Reports). While not required, as a best practice, Scripts should include a Return Type.

Return Types

When processed, Actions trigger system responses to a defined list of Return Types. An Action can return zero or more return type result sets. If more than one return type is returned, the system will respond to each item in the order returned.

Below is a listing of each Return Type, the response it triggers and allowable fields (data types, and field descriptions) to call.

Return Type	Description	Fields	Data Types	Field Description	Additional Information
Message	Displays a message box on the screen	reterr	numeric	Greater than 0=Success, Less than 0=Error
		retmsg	nvarchar	The message to display on screen
Applet	Opens an InFocus Applet	appletname	nvarchar	The name of the applet to open	Chart of Accounts, Clients, Disbursement Journal, Employee Reimbursables, Employees, General Journal, Projects, Project Planning, Purchase Journal, Receipt Journal, Sales Journal, Time Sheet, Vendors, Expense Sheets, Timesheet Adjustments
		keyid	int	The ID of the record to load in the respective applet
DocID	Downloads a document from Document Manager	docid	int	The ID of the document record to download	Please note, this return type bypasses defined permissions set on the document(s).
Web Call	Makes a call to the web	BrowserWidth	int	If opening a browser, this sets the width
		BrowserHeight	int	If opening a browser, this sets the width
		Content	nvarchar	The override data to post to the weburl
		ContentType	nvarchar	The content type header (default is application/x-www-form-urlencoded)
		Debug	bit	When true, the response will be added to the InFocus SQL Watcher
		FilePath	nvarchar	For uploading files. If set, this will automatically set the method to post and the contenttype to multipart/form-data
		Format	nvarchar	Format to utilize in the web call	Allowed formats are: FORM, JSON, or XML (default is FORM)
		IncludeParams	bit	When true, the parameters from the Action will be posted in the format specified
		IsDocManagement	bit	When true, and a file is being uploaded, it will also post the necessary fields for the listening Document Management service
		Method	nvarchar	Method to utilize in the web call	For example: GET, POST, PUT,HEAD, etc. The default is GET
		OpenURL	nvarchar	Opens a browser to the specified URL
		ParamQuerystring	bit	If true, the included parameters will be appended to the URL as a query string
		Password	nvarchar	The password for basic authentication
		ResponseProcedure	nvarchar	If specified, the web response is passed to the procedure specified in a variable called @response nvarchar(max)
		ShowResponse	bit	If true, the response will be shown in a browser window
		URL	nvarchar	The URL to be called
		UseBasicAuth	bit	If true, the basic authentication header will be added.	Username and Password must be present
		Username	nvarchar	The username for basic authentication
		Delay	int	number in milliseconds to wait after processing (good for pausing if making a lot of calls to the same URL)
Action		CVSReportID	int	Launches the system "action" / "report"
		CUSReportID	int	Launches the custom "action" / "report"
		ShowDialog	bit	If true, and DefaultParams are passed in, it will still show the dialog.
		ToFile	bit	If true, the output will be saved to file
		Filename	nvarchar	The full path to the file to save
		ToDocMgt	bit	if true, the file will be saved to document mgt
		DocAppId	int	The Document Applet Type ID (from table DocAppletTypes)
		doc_KeyId	int	The relative doc type
		doc_<AppletName>	int	Additional columns in the format doc_appletName (from the table DocAppletTypes without the space) where the value is the key. For example, doc_salesjournal with value 1 would associate the document to the Sales Journal SJID 1
		ToEmail	bit	if true, the same fields for email can be supplied. Filename can be comma separated
		param_name	string	param_ precedes the name of the parameter to pass into the action being run. for example param_projectpath would pass the value in that column into the ^projectpath^ parameter in the action being run.
		CVSDocTypeId	int	the primary system document type (folder)
		CUSDocTypeId	int	the primary custom document type (folder)
Email
		RecipEmail	string	the comma separated list of "To's"
		CC, BCC, Subject, Body	string	normal email fields
		FromAddress, FromName	string	the from info
		SmtpServer	string	Optional (defaults to Global Settings>Document Management>Email Relay Settings)
		SmtpUser	string	Optional (defaults to Global Settings>Document Management>Email Relay Settings)
		SmtpPass	string	Optional (defaults to Global Settings>Document Management>Email Relay Settings)
		SmtpPort	int	Optional (defaults to Global Settings>Document Management>Email Relay Settings)
		UseSSL	bit	Optional (defaults to Global Settings>Document Management>Email Relay Settings)
		DocId	int	If supplied, emails the document
		Filename	string	comma separated list of file path's to attach
Power shell	Runs powershell script. Note! Powershell must be installed on both developer and end-user machines for Powershell Actions to run.
		$infocus	object	The powershell parameter that gets passed in from InFocus
		.RetErr	int	Return Number, negative is an error
		.RetMsg	string	Return Message
		.Db	SqlConnection	SqlConnection (unopened) pointing to InFocus Database
		.Tx	SqlTransaction	SqlTransaction if in a transaction pipeline
		.Error	Exception	Internal Exception
		.Username	string (readonly)	The current InFocus Username
		.UserId	int (readonly)	The current InFocus User Id
		.EmpId	int (readonly)	The current InFocus Employee Id
		.EmpCode	string (readonly)	The current InFocus Employee Code
		.EmpName	string (readonly)	The Current InFocus Employee Name
		.KeyId	int	The primary key of the current record (if applicable)
		.AppletName	string	The name of the executing applet (if applicable)
		.Dataset	Dataset	Optional dataset property that will allow reports to be run

Additional Considerations

Using SQL RAISEERROR

When processing Actions, it’s worth noting that while Return Types define the output of an Action, they don’t necessarily reflect the output of the event that fired the action.

So, if an On Save action errors out, the On Save event that fired it still occurs. For example: If you created an action to email Time Approvers after a submitted timesheet is saved (On Save) and the action errors out, the Timesheet is still saved. If you want to make your event contingent on the success of the Action, the Action must include an explicit SQL RAISEERROR (severity 11) which would then rollback the event.

Overview