Custom Scripts

A custom script is the script used by an Execute Script command to execute custom functionality. The Execute Script command provides a list of predefined scripts that can be used directly or edited to suit specific needs. Please see the Execute Script topic for more information about how to use the predefined scripts.

A custom script can be added to an Execute Script command by setting the Script type to Custom Script:

The following example writes extracted data to a database. Normally a Data Export Script would be used to write extracted data after an agent has completed, but an Execute Script command could be used to write data as it's being extracted:

using System;
using Sequentum.ContentGrabber.Api;
using Sequentum.ContentGrabber.Commands;
public class Script
{
public static CustomScriptReturn CustomScript(CustomScriptArguments args)
{   IConnection connection = args.GetDatabaseConnection("exportDatabase");
    connection.OpenDatabase();
    try
    {
    ICommand command = connection.GetNewCommand();
    command.SetSql("insert into export_table values (@title, @description)");
    command.AddParameterWithValue("title", args.DataRow["title"], CaptureDataType.ShortText);
    command.AddParameterWithValue("description", args.DataRow["description"], CaptureDataType.ShortText);
    command.ExecuteNonQuery();
    }
    finally
    {
    connection.CloseDatabase();
    }
    return CustomScriptReturn.Empty();
}
}

NOTE: To use the above example code in the agent, one must need to import the below library, which is not added in "Execute Script" by default.

using Sequentum.ContentGrabber.Commands;

The above script uses the IConnection and ICommand interfaces which are part of Sequentum Enterprise Script Utilities.

The script must have a static method with the following signature.

public static CustomScriptReturn CustomScript(CustomScriptArguments args)

The script must return an instance of a class CustomScriptReturn. This class has the following 4 public static methods:

Property or Function	Description
static CustomScriptReturn RetryCommand()	The agent will retry the specific command if an error occurs.
static CustomScriptReturn RetryContainer(IContainer container)	The agent will retry the specific container command. The container command must be a parent of the current command.
static CustomScriptReturn ExitContainer(IContainer container)	The agent will exit the specific container command. The container command must be a parent of the current command.
static CustomScriptReturn Pause()	The agent pauses and displays an agent web browser, which allows a user to interact with the web browser before continuing processing.
static CustomScriptReturn Empty()	The agent continues its normal executing flow.

An instance of the CustomScriptArguments class is provided by Sequentum Enterprise and has the following functions and properties:

Property or Function	Description
Agent Agent	The current agent.
ScriptUtils ScriptUtilities	A script utility class with helper methods. See Script Utilities for more information.
Command Command	The current agent command being executed.
IContainer ParentContainer	The parent container command of the current command.
IConnection DatabaseConnection	The current internal database connection used by the agent. This connection is already open and should not be closed by your script.
IHtmlNode HtmlNode	The extracted HTML node.
IHtmlDocument HtmlDocument	The current HTML document.
IInternalDataRow DataRow	The current internal data row containing the data that has been extracted so far in the current container command.
IRuntimeData RuntimeData	Provides access to the internal database.
bool IsDebug	True if the agent is running in debug mode.
bool IsSchemaOnly	If true, only the data schema is required, so you can optimize processing by only returning the data schema with no data.
int RetryCount	The number of times this command has been retried.
bool IsParentCommandMissingSelectionOrData	This parameter is set to true if the parent container's selection was not found, or is iterating through an empty data list.
bool IsParentCommandActionError	This parameter is set to true if the parent action command encountered an error while executing the action command.
bool HasDoneAction	This parameter is set to true if the parent action command triggered an action in the web browser.
IInputData InputDataCache	All input data available to the current command.
BrowserResponse LastErrorResponse	The last error response from the web browser. This will contain any errors messages when loading a new web page.
void WriteDebug(string debugMessage, DebugMessageType messageType = DebugMessageType.Information)	Writes log information to the agent log. This method has no effect if agent logging is disabled, or if called during design time. debugMessage - The log message. messageType - The log message type. The agent log level specifies what information is written to the log. If the log level is set to Low for example, only errors are written to the log.
void WriteDebug(string debugMessage, bool showMessageInDesignMode, DebugMessageType messageType = DebugMessageType.Information)	Writes log information to the agent log. This method has no effect if agent logging is disabled, or if called during design time. debugMessage - The log message. showMessageInDesignMode - Set to True if you want to see debug messages in design mode. messageType - The log message type. The agent log level specifies what information is written to the log. If the log level is set to Low for example, only errors are written to the log.
void WriteInfo(string debugMessage, params object[] pars)	Writes log information to the agent log. This method has no effect if agent logging is disabled, or if called during design time. debugMessage - The log message. pars - A variable number of parameters used in the debug message.
void WriteError(string debugMessage, params object[] pars)	Writes log error to the agent log. This method has no effect if agent logging is disabled, or if called during design time. debugMessage - The log message. pars - A variable number of parameters used in the debug message.
void WriteWarning(string debugMessage, params object[] pars)	Writes log warning to the agent log. This method has no effect if agent logging is disabled, or if called during design time. debugMessage - The log message. pars - A variable number of parameters used in the debug message.
void Notify(bool alwaysNotify)	Triggers notification at the end of an agent run. alwaysNotify - If alwaysNotify is set to false, this method only triggers a notification if the agent has been configured to send notifications on critical errors.
void Notify(string message, bool alwaysNotify)	Triggers notification at the end of an agent run, and adds the message to the notification email. message - The message to add to the notification email. alwaysNotify - If alwaysNotify is set to false, this method only triggers a notification if the agent has been configured to send notifications on critical errors.
void AddNotificationMessage(string message)	Adds a message to the notification message, but does not trigger a notification. message - The message to add to the notification email.
GlobalDataDictionary GlobalData	Global data dictionary that can be used to store data that needs to be available in all scripts and after agent restarts. Input Parameters are also stored in this dictionary.
IConnection GetDatabaseConnection(string connectionName)	Returns the specified database connection. The database connection must have been previously defined for the agent or be a shared connection for all agents on the computer. Your script is responsible for opening and closing the connection by calling the OpenDatabase and CloseDatabase methods.
IInputDataRow GetInputData()	If the current command is a data provider, the data for that command is returned. Otherwise, this function searches the command's parents and returns the first found input data.
IInputDataRow GetInputData(Command command)	If the specified command is a data provider, the data for that command is returned. Otherwise, this function searches the command's parents and returns the first found input data.
IInputDataRow GetInputData(string commandName)	If the specified command is a data provider, the data for that command is returned. Otherwise, this function searches the command's parents and returns the first found input data.
IInputDataRow GetInputData(Guid commandId)	If the specified command is a data provider, the data for that command is returned. Otherwise, the function throws an error.
void RotateProxies(bool isRemoveCurrentProxy = false)	Moves to the next proxy before next page load. isRemoveCurrentProxy - indicates if remove a current proxy from the proxy list
void SetProxy(string proxyAddress)	Sets a single proxy in global data and makes that the active proxy. All current proxies in global data will be removed.
void SetProxy(string proxyAddress, string username, string password)	Sets a single proxy in global data and makes that the active proxy. All current proxies in global data will be removed.
void SetPageLoadError(string errorMessage)	Logs a page load error and mark the page for retry if the agent errors are later retried. errorMessage - The error message to log.
CustomDataStorage GetOrAddDataStorage(string storageName, string key, CustomDataColumns columns)	Returns a custom database table storage that can be used to store persistent data while running an agent. A new storage is created if it does not already exist. The storage is created in the internal database. storageName - The name of the storage. key - A value indentifying a sub-storage. columns - Data field definitions for the storage.
ContainerDataDictionary ContainerData	Container data dictionary that can be used to store data that needs to be available in the current container command and all sub-commands of the current container.