Programming Interface

Sessions allow you to run multiple instances of the same agent at the same time. This is particularly useful when running an agent directly from a website where you can have many web users visiting the website at the same time. Each web user can start the agent in their own session and the user will only see agent progress status and extracted data belonging to his session.

Running an Agent in a Session

To run an agent in a session, you must specify a session ID when you run the agent and the agent must be configured to support sessions. To configure an agent to support sessions, set the agent option Support Sessions to Multiple Sessions in the Sessions section on the Advanced options tab.

A session ID can be specified when running an agent via the Agent API or the Agent Proxy. You can use any string as session ID, but each session must have a unique ID, so you would normally use a unique identifier. The following C# code snippet runs an agent with a unique session ID:

string sessionId = Guid.New().ToString();

AgentApi agent = new AgentApi("sequentum", sessionId);

agent.StartAgent(new AgentSettings());

A session ID can also be specified when running an agent from the commandline by using the command-line option session_id. The following command line input runs an agent named sequentum with a session ID ry37456r.

RunAgent.exe "sequentum" session_id "ry37456r"

Session Data Cleanup

When running an agent normally without sessions, the agent can cleanup previously extracted data and status information before it starts because only data and status from the last run is important. Data cleanup becomes much more complex when running agent sessions. An agent session should only cleanup data from its own session, so it cannot do a general cleanup of all data belonging to the agent. Since all sessions are normally new sessions there is no previous session data to cleanup, and the agent cannot cleanup data when it completes a session since you'll need access to the data for some time, so session data risks hanging around forever.

You can manually trigger a session cleanup by calling the API method CloseSession, but in a web application you may not always be able to tell when a user session ends. When running an agent in a session you can specify a session timeout, and the session cleanup will start automatically after the agent session completes and the specified timeout has passed. This gives your application a minimum amount of time to use the session data before it's removed.

An agent only cleans up externally exported session data if the agent is configured to export data to a database. If you are using an Export Script or if you are exporting to a file format, then you are responsible for any cleanup of exported session data.

You may not always want to remove externally exported session data automatically when an agent session ends. To prevent session data from being removed, set the agent option Cleanup External Session Data to false. This option can be found in the Sessions section on the advanced options tab.

If you are not using the API to retrieve extracted data, but are only working with externally exported session data, then you can set the option Remove Session to Immediately to remove internal session data immediately after it has been externally exported. This will reduce the size and increase performance of the internal database. Session status information is not removed and will still be available until the session timeout has passed.