Overview

This document will cover installation and usage Automation Agent. Throughout this documentation, Automation Agent is frequently abbreviated as AA.

• Setting up Automation Agent
• Basics of Automation Agent
• Creating a Job in Automation Agent
• Installing Automation Agent as a Service
• Uninstalling Automation Agent from Services
• Starting/Stopping Automation Agent as a Service
• Automation Agent Service Logs

Setting up Automation Agent

To set up AA the first time you must have:

• SQL credentials with access to master
• SQL credentials to the server you will be using (these can be the same)
• A license code and email (SalesPad will provide this)
• Remote Library installed (it is not required to be installed before installing AA, but AA doesn’t work without it)

AA can be set up on its own database. Setting up a separate test environment is not necessary, but it is recommended. The first time AA is launched, it will display a Welcome screen. Here the user can select either Get Started or, if AA has been installed on the system prior, they can select Skip Set Up and continue to the Login screen.

On the next screen, the user will select the SQL server they would like to connect to. This server is where Automation Agent will set up its tables. Connections do not have to be on the same server that SalesPad is installed on.

Next is the Database Setup screen. Here the user can either create a new database or choose an existing database on the server from the previous page. AA will then prompt for the user to set up an admin user. The user completing these steps will be the user who logs in when Login screen appears for the first time. Other users can be set up within the application after initial setup is complete.

The Editing Connection screen is a condensed version of all the previous screens and will allow the user to set up new connections, create a new database, or install Automation Agent into other existing databases.

Note: The user completing these steps needs to have access to the master and the database you select or create, therefore it is recommended to use the Admin SQL user profile here.

The final page is the licensing page and will require a valid license code and email (we will provide this for you). At this point, you should be completely set up and AA will launch.

Basics of Automation Agent

AA’s opening screen will look like the one below.

Users should notice that, when closing AA, clicking the X button will simply dock AA and not actually close the application. To close it, you must open the blue dropdown and click Exit.

Clicking the Job Search button will open a tab below the ribbon that will auto search all of your saved jobs, if any exist.

Creating a Job in Automation Agent

Jobs in AA contain steps, schedules, and a run history. On the Job Edit screen users can edit the job’s name, enable or disable the job, view the steps, view its schedules, and view its history.

Creating and Editing Jobs

The Jobs Step editor can be opened by pressing the New button on the Steps tab, or by clicking the hyperlink on an existing job.

The Job Command portion of the Job Step Editor will be loaded for each different Command Type (see above). Each job step requires a name (1), and Command Type (4) to run. The Seq field (3), in general, can be left as 0. However, if one job needs to run before a separate job, the sequence can be set to any positive or negative value. The steps will be run in order of sequence first, and then by Step ID. Job Steps can be individually toggled by enabling or disabling them (2). If the job is disabled, this field will not matter, as no job steps will run on a disabled job.

Job Command Types

When a Command Type is selected, the fields labeled appear in the Job Command tab. These fields are different for each Command Type, and if the Command Type is changed, all the data on the form is lost. There are currently seven different Command Types in AA:

• Forward Sales Batch
• Forward Sales Doc ID
• Invoice Sales Batch
• Remove Sales Batch Holds
• Run Script
• Update Batch Entered
• Email

Every Command Type other than Email requires a SalesPad Remote URL (2). This can be found in SalesPad Desktop when you start the web service. In addition, there is an option to append a sales document audit (1) to several of the Command Types.

Forward Sales Batch

The Forward Sales Batch command will forward all documents in a given batch. This command will require that you provide a Sales Batch (1) and the SalesPad Remote URL (3). If desired, you can create a delay which leaves documents in the batch for the specified number of minutes (4) and hours (5). In addition, you can create an audit (6), restrict to a specific Doc ID (2), and use Workflow plugins (7). The Sales Doc ID needs to have the same name as the Doc ID in the Workflow set up in SalesPad Desktop. If left blank, it will select from all Doc IDs. Similarly, the batch needs to have the same name as the batch created in Workflow. If the Use Workflow Plugins (7) box is not checked, then plugins selected in Workflow will not run. Please also note that not all plugins are able to be used from an automated Workflow because they require user input or have not been set up to be automated.

Forward Sales Doc ID

The Forward Sales Doc ID command is very similar to the Forward Sales Batch, however, it forwards all sales documents in the provided batch. This command will require you to provide the Sales Doc ID (1) and the SalesPad Remote URL (2). This command will always append an audit and will never use Workflow plugins.

Invoice Sales Batch

The Invoice Sales Batch command will attempt to transfer all orders in the provided Sales Batch (2) with the provided Doc ID (3) to an invoice. This works very much like Batch Processing in SalesPad Destktop and is the equivalent of searching for a given batch, filtering by the Doc ID, and clicking Transfer. This command requires that you provide the SalesPad Remote URL (1), the Sales Batch (2), and Doc ID (3). If Use Order Number As Invoice Number (4) is not checked and the SalesPad Desktop setting is false, the command will create an invoice with a new invoice number. However, if this is unchecked and SalesPad normally uses the order number as the invoice number, then it will still use the order number as the invoice number. If this box is checked, it will always use the order number as the invoice number. When Send To Batch on Failure (5) is checked, all documents that failed to transfer to invoice are sent to the Failure Batch (6). If this box is checked, then a Failure Batch is expected to be provided.

Remove Sales Batch Holds

Remove Sales Batch holds will remove the provided holds (3) from the documents in the provided batch (1) with the provided Doc ID (2). This command requires that you provide information for all fields. If Append Sales Document Audit (5) is not checked, the removal of the holds will not be audited. The Holds field (3) can contain multiple fields separated by semicolons.

Run Script

The Run Script command will allow you to run a C# script from AA in the SalesPad Desktop environment. The command requires that you provide information for all fields, namely Script Text (1) and the SalesPad Remote URL (2). The script is very similar to a run script, except that it will not be passed through any parameters. It will have the same libraries included and will be run in the same namespace. If Remote Library is running as a service, the script will not have access to the GUI and will cause an error if it attempts to access it. It is recommended that scripts here do not attempt to provide messages, except during the debugging process.

Update Batch Entered

The Update Batch Entered command will attempt to update the time entered for all documents in the given Sales Batch (1) and Doc ID (2) to the current system time. This command requires Sales Batch name (1) and SalesPad Remote URL (3). Both Sales Batch and Doc ID can use anything allowed in a SQL-like match.

Email

The Email command is the only command that does not require a URL and does not need Remote Library to run. The Send To (1), From Email (8), Server (10), Port (13), Use SSL (14), User (11), and Password (12) fields are all required. The fields in the top section (those fields above the Send As Attachment (6) checkbox) all directly correlate to email fields. The bottom section pertains to server setup. The Server (10), Port (13), and Use SSL (14) fields need to match the requirements from your email server. As an example, data for Gmail would be

Server: smtp.gmail.com
Port: 465 or 587
Use SSL: True

The User (11) and Password (12) fields should be the login credentials used to log in to the mail server. The FromEmail (8) field must be an email the user is allowed to send from. The FromName (9) field is optional. If left blank, the mail server will use the default stored on the server itself. If Send As HTML (7) is checked, it will format the email as HTML. Otherwise, it will send it as raw text. File (5) is the path for the file that should be attached or inserted into the body as raw text.

Remote Library URL

If you start the Remote Library self-hosted (not installed as a service), it will display the following data. The circled URL is the URL needed for job steps. The displayed URL is the default URL for Remote Library; if there is also a REST URL, that URL can be ignored for AA.

Creating and Editing Job Schedules

All schedules require a Freq Type (3), and should have a Schedule Name (1). Names do not have to be unique, though it is recommended for identification purposes. Schedules are associated with specific jobs and cannot be applied to multiple jobs or reused. The Frequency Type determines which fields are editable and what type of schedule is being created. Most frequency types will require the Within the Day and Date Limitations sections to be filled out. In addition, schedules can be enabled or disabled by checking the Enabled (2) checkbox.

For all schedules, all of the editable fields must be filled out correctly in order to successfully save the schedule.

Daily Frequency

Daily Frequency allows a job to run one or more times within the day and can be set to run every one or more days. The Run Every (1) field, which will determine how often this job runs, should be greater than one. Start Time (2) will determine the time the job will start running in the day and End Time (3) is time in the day it will stop running. The Units dropdown (5) can be either seconds, minutes, or hours and will determine the units for the Run Every (4) field. In the Date Limitations section, Start Date (6) is the first date that the job will run and End Date (7) is the last date it will run. The end date must be after the start date, and there is not a way to not use an end date.

Day of Month Frequency

The Day of Month schedule allows a job to run every month on a particular numerical date. It is recommend to use the Relative Day of Month schedule for running jobs at the end of the month. The job can run multiple times within the day by setting up the Within the Day portion as well. The Runs Every (2) field should be set to one or greater.

One Time Frequency

The One Time schedule will only run once, and the Run Every (3) field can be left blank. This schedule will find the first time that it should run as if it were a daily schedule, run, then disable itself.

Relative Day of Month Frequency

The Relative Day of Month schedule can be used to run a job on a particular day of every month, such as the first Sunday, every second Tuesday, or last Saturday, and when combined with the Run Every (2) field, it can run every n months. The Run On (1) field can be First, Last, Second, Third, or Fourth, and Of The Month (3) can be Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Weekday, or Weekend.

Runs on Start Up

This schedule is generally used for testing or for jobs that need to run every time the computer starts. This will cause the job to run as soon as it can after the Job Processor starts.

Weekly Frequency

The Weekly schedule can be used to run a job on certain day(s) of the week, every one or more week. The Run Every (1) field should be greater than zero. The On These Days (2) field is a dropdown that will allow the user to select one or more day of the week.

Using the Job Processor

The Job Processor screen is a simple screen that displays all the schedules in the grid in the center of the screen (1). This is where the user can start and stop the Job Processor and install or uninstall AA as a service. The Schedule Name is a hyperlink and can be used to edit the selected schedule.

When the Job Processor is running it will reload the schedules every five minutes by default. This interval can be changed in the settings.

Note: The processor will function differently when AA is installed as a service.

Installing Automation Agent as a Service

To install AA as a service, launch AA and navigate to the Job Processor screen. On the Processor screen, click the Install Service button.

Note: If AA is already installed as a service, this button will be called Reconfigure Service.

An installation window with the option to select Automatic or Manual will open.

To reconfigure the AA service while it is already installed click “Reconfigure Service” that used to be the “Install Service” button if the service is installed. This will take you through the same process as installing the service.

Uninstalling Automation Agent as a Service

If AA is installed, the Uninstall Service button to the right of the Install/Reconfigure Service button should be available to click.

To uninstall, click the Uninstall Service button. The buttons on the top should be inactive and the mouse should be in the loading status when you hover over the tool strip. When the uninstallation completes, the screen will refresh. If there was an issue, there will be a pop-up window with information on why it was unable to uninstall the service.

Starting/Stopping Automation Agent as a Service

Make sure that the service is installed before attempting to start or stop the service. When the service is installed, the Start and Stop buttons will take longer to complete their operation. If anything goes wrong during starting or stopping, you will be notified with a small pop-up.

Note: The grid that normally contains the schedules and information on what is currently going on with the service is empty when the service is installed. This is because the service is detached from the application when it is installed. The service can also be started and stopped from the Services application in Windows. However, if it fails to start or stop, the errors can be significantly less helpful. If anything does go wrong, check the logs to see more detail on the error.

Automation Agent Service Logs

AA logs to the Job History table normally, when it is installed as a service, and the logs can be checked on the History tab of jobs. However, it also logs extra information about it starting, stopping, and any other errors that occur during the execution of a job, in the Windows logs. If it happens to have an unhandled exception, it will be logged to the Windows Logs\Application and will most likely be an error-level log. The AA service will also create a log called Service.SalesPad.AutomationAgent.Log. This log will contain start and stop information, along with start and completion of job steps logged.