Skip to main content

VisualCron Web API​

The VisualCron Web API lets other programs and scripts work with a VisualCron Server over HTTP. You can list, run and stop Jobs and Tasks, read log entries, and read or set Variables. The Web API has a REST service, which returns text, XML or JSON, and a web service (SOAP). This page is for developers and administrators who integrate VisualCron with other systems. To use the full .NET library instead, see VisualCron API.

Turn on the Web API​

The Web API is off by default. To turn it on:

  1. Go to Server -> Main settings -> Settings and select the Web API tab.
  2. Select Allow Web API.
  3. Change the Port of the Unencrypted and Encrypted boxes if you need to. The defaults are "8001" and "8002".
  4. Click Apply settings.

To check that it works, open http://localhost:<port>/VisualCron/text/Docs in a browser on the Server, with the unencrypted port. The page lists the Web API methods.

Server settings window, Web API tab, with the Allow Web API option, the Unencrypted box with port 8001 and its Web service, REST service and REST service documentation links, and the Encrypted box with port 8002, the Use self signed certificate and Use user certificate options and Force Windows Authentication

  • Allow Web API: when it is checked, the Server opens both Web API ports
  • Use self signed certificate: the encrypted port uses a certificate that VisualCron creates for "localhost". It suits calls from the Server itself
  • Use user certificate: for calls from other computers, select a certificate from Global - Certificates that has a private key that can be exported, is issued to the Server's name and is trusted by the calling computers. If VisualCron cannot use the selected certificate, the encrypted port uses the self-signed certificate instead, and calls that use the Server's name fail the certificate check
  • Force Windows Authentication: the encrypted port accepts only callers that authenticate with a Windows account. The unencrypted port does not use it

For every option on the tab, see Settings - Web API.

VisualCron does not open the Web API ports in Windows Firewall. To call the Web API from other computers, allow its port through Windows Firewall.

warning

Only allow local connections on the Users/Logon tab does not apply to the Web API. While Allow Web API is checked, the Server accepts Web API logons from any computer that can reach the Web API ports. To keep the Web API local, do not allow its ports through the firewall, or clear Allow Web API.

Users and permissions​

Each Web API call runs as a VisualCron user. Add the user in the Manage user permissions window first. The Server checks that user's permissions on each call, except as noted in Permissions.

Available methods​

When the Web API is on, the Docs page lists every method with its parameters, its return type and the default columns of its text output. The Docs page does not need a logon:

http://localhost:8001/VisualCron/text/Docs

Log on​

To get a token, call the logon method with a user name and password: http://localhost:8001/visualcron/text/logon?username=admin&password=qwerty123

The logon method takes these parameters:

ParameterRequiredDescription
usernameYesThe VisualCron user name
passwordNoThe user's password
expireNoHow long the token stays valid, in seconds. Default "3600" (1 hour); "0" also gives 3600

The response holds two values, Result and Token. In text output, the first line is the header row and the second line holds the values:

result,token
OK,<token>

Result is "OK" when the logon succeeds. When the logon fails, Result gives the reason, for example "WrongPassWord" or "NoSuchUser", and no token is returned. In JSON output, Result is a number: "3" means OK, and other numbers give the reason. Check Result before you use the token.

Token lifetime and logoff​

Pass the token as token=<token> on each later call, for example:

http://localhost:8001/visualcron/text/job/List?token=<token>
  • The token is valid for the expire time, counted from the logon. Calls do not extend it
  • After the token expires, calls return "Permission denied" (see Errors). Log on again to get a new token
  • Tokens are also cleared when the VisualCron Server service restarts, and when you change a Web API Port or Allow Web API and apply the settings
  • The Server checks the token again when a call ends. If the token expires while a synchronous Job/Run or Task/Run is in progress, the call returns "Permission denied" even though the Job or Task ran. Log on with an expire longer than the longest run you expect

To end the session before the token expires, call logoff:

http://localhost:8001/VisualCron/text/logoff?token=<token>

logoff returns true when the token existed and was removed, and false otherwise. In text output, the value is "True" or "False", after an empty header line.

Log on in each call​

A token costs one extra call at the start, and later calls do not log on again. Instead of a token, you can pass username and password on each call, and each call then logs on and runs the method. The Contains methods need a token. For example: http://localhost:8001/visualcron/text/job/List?username=admin&password=qwerty123

Call a method​

A REST call is an HTTP GET request to this address:

http://<server>:<port>/VisualCron/<format>/<method path>?token=<token>&<parameters>

<method path> is the path of the method on the Docs page, for example Job/List or Log/Job/List. On the encrypted port, use "https". The <format> part selects the output:

FormatPathOutput
Text/text/Plain text: a header row, then one line per object
XML/xml/XML
JSON/json/JSON

The same Job list in each format:

https://localhost:8002/visualcron/text/job/list?token=<token>
https://localhost:8002/visualcron/xml/job/list?token=<token>
https://localhost:8002/visualcron/json/job/list?token=<token>

The object, method and parameter names are the ones on the Docs page. Use the parameter names in the method's address on the Docs page. The method's parameter list can show a different name, for example expireTime for expire, and a parameter with that name is ignored without an error.

  • One Job: call Job/Get with its Id
  • Shorter list: add filters to Job/List. filters=Contains:<text>, NotContains:<text>, Equal:<text> and NotEqual:<text> match the Job name, and case is ignored. URL-encode <text>
  • Several filters: separate them with commas. A Job must match all of them. Because commas separate filters and a colon follows the filter name, the text itself cannot contain a comma or a colon
http://localhost:8001/VisualCron/text/Job/Get?id=<job Id>&token=<token>&columns=id,name,runmissed
http://localhost:8001/VisualCron/text/Job/List?filters=Contains:<text>&token=<token>

Text output options​

These parameters apply to text output only:

ParameterValuesDefaultDescription
includeHeaders"true" or "false""true"Adds the header row with the column names
columnsColumn names, separated by commasThe method's default columns, listed on the Docs pageThe columns to return, in this order. Case is ignored
fieldSeparatorA decimal character code"44" (comma)The character between values
textQualifierA decimal character code, or "0" for none"0" (none)The character around each value
lineBreakA decimal character code"10" (line feed)The character between rows

For example, to separate values with a semicolon (59) and put double quotes (34) around each value:

http://localhost:8001/VisualCron/text/Job/List?token=<token>&fieldSeparator=59&textQualifier=34&lineBreak=10

Run a Job​

To run a Job, call Job/Run with the Job's Id. In every call, pass synchronous, checkConditions, updateVariables and raiseTriggerEvents explicitly, each set to true or false, and do not rely on a default for them. With synchronous=true, the call waits for the Job to finish and returns its exit code. With synchronous=false, the call returns when the Job has started. For example, with <base address> standing for http://<server>:<port>/VisualCron/json:

<base address>/Job/Run?token=<token>&id=<job Id>&synchronous=true&checkConditions=true&updateVariables=true&raiseTriggerEvents=true
ParameterRequiredDefaultDescription
idYesNoneThe Id of the Job
synchronousNoPass it explicitlyWith true, waits for the Job to finish before the call returns
checkConditionsNoPass it explicitlyWith true, checks the Job's Conditions before the run
updateVariablesNoPass it explicitlyWhether the run updates the Job Variables ("Update job variables" on the Docs page)
raiseTriggerEventsNoPass it explicitlyWhether the run raises Trigger events, so that event Triggers can react to it
runFromTask, runFromTaskIdNo"false", noneWith runFromTask=true, starts the run at the Task with this Id
runToTask, runToTaskIdNo"false", noneWith runToTask=true, ends the run at the Task with this Id
variablesNoNoneJob Variables for the run, as <name>=<value> pairs separated by |. A value cannot contain "=" or "|"

In every Task/Run call, pass checkConditions, synchronous and raiseEventTriggers explicitly in the same way. In Task/Run, the Trigger events parameter is raiseEventTriggers.

The result holds JobStartedResult, ExitCode and ExitCodeResult. In text output, ask for them with columns=JobStartedResult,ExitCode,ExitCodeResult. In text and XML output, JobStartedResult and ExitCodeResult are names. In JSON output, they are numbers. In XML output, ExitCodeResult is in the R element.

  • Started and succeeded: JobStartedResult is "Started" ("1" in JSON) and ExitCodeResult is "Success" ("1")
  • Ran and failed: ExitCodeResult is "Failure" ("2"), and ExitCode holds the Job's exit code
  • Queued: JobStartedResult is "Queued" ("3"). The Job runs later
  • Not started: any other JobStartedResult, for example "NotStarted" ("0") or "NotStartedBecauseItWasAlreadyRunning" ("2")
  • Unknown Id: if no Job has that Id, the result is empty ({} in JSON output), not an error

With synchronous=false, the call returns before the Job ends, so ExitCode and ExitCodeResult do not give the Job's result. Check the result in the Job's log.

Permissions​

Each method checks the permission of the logged-on user. Where a method has its own row, that row applies:

MethodsPermission the user needs
Get, GetByName, ListRead on the object type, for example Read on Jobs for Job/List. User and UserGroup use Users, JobVariable, VariableValue and JobVariableValue use Variables, Connection uses Connections, ConditionSet uses Conditions, ExitCodeCollection uses Exit codes, and TimeExceptionCollection uses Time exception collections
Job/RunExecute on the Job
Task/RunExecute on Tasks
Activate, DeActivateEdit on the object type
RemoveDelete on the object type
Job/Stop, Task/StopDelete on Processes
Job/Processes, Task/ProcessesRead on Processes
Task/Output, Task/OutputHistoricRead on Tasks
Trigger/ListRead on Jobs
Trigger/Get, Trigger/Activate, Trigger/DeActivateEdit on Jobs
Log/General/List, Log/Job/List, Log/Task/List, Log/Audit/ListRead on Log
Variable/Set, JobVariable/SetRead on Variables, plus Edit to change a Variable or Add to create one
License/Activate, License/DeactivateExecute on License
ContainsA valid token only

Job/List returns every Job when the user has Read on Jobs.

A Job started with Job/Run is not tied to the user, so the Server does not check that user's permissions on the Credentials the Job uses. A Task started with Task/Run is tied to the user, and the Server checks Read and Execute on each Credential the Task uses, for that user (see Main - User Permissions). To control which Jobs a Web API user can run, use Execute on the Jobs.

Trigger/Remove is listed on the Docs page but returns an error. Remove Triggers in the Client.

Errors​

  • "Permission denied" message: the call was refused. The message names the method, for example Permission denied. Method: job.run., and comes in the format of the call
  • Message that ends with "User:" and a user name: the token is valid, but that user lacks the permission. Logging on again does not help
  • Message that ends with "Token:" and the token you passed: the token is unknown or has expired. Log on again
  • Message that ends with "Token:" and nothing after it: the call had no token, for example because it passed username and password. The user name or password was not accepted, or the user lacks the permission
  • Cause not clear: "Permission denied" can mean an expired token, a wrong user name or password, or a missing permission. Log on again once. If the call is still refused, check the user's permissions
  • "Permission denied" after Job/Run or Task/Run: the Job or Task may have run although the call was refused (see Token lifetime and logoff). Check the Job's result in the log before you run it again
  • A failed logon: a Result other than "OK" (see Log on)
  • Other errors: an HTTP error response instead of a result

To check whether an object exists, call its Contains method with a token, for example Job/Contains?id=<job Id>&token=<token>. It returns true or false ("True" or "False" in text output).

2. Web service/SOAP

It is also possible to communicate with VisualCron through the web service API. The wsdl URL can be found in the Web API tab in Server settings.

There is the following example in the API folder (sample TestClient project):

var binding = new BasicHttpBinding()
{
MaxBufferPoolSize = int.MaxValue,
MaxReceivedMessageSize = int.MaxValue,
ReaderQuotas =
new XmlDictionaryReaderQuotas()
{
MaxArrayLength = int.MaxValue,
MaxStringContentLength = int.MaxValue,
MaxNameTableCharCount = int.MaxValue
},
Security = new BasicHttpSecurity()
{
Mode = BasicHttpSecurityMode.TransportCredentialOnly,
Transport = new HttpTransportSecurity()
{
ClientCredentialType = HttpClientCredentialType.Basic
}
}
};

var client = new WebServiceClient(binding, new EndpointAddress("http://localhost:8001/VisualCron"));
//or just:
//
//var client = new WebServiceClient();
//
//but better setup binding

if (client.ChannelFactory.Credentials != null)
{
//set Credentials
client.ChannelFactory.Credentials.UserName.UserName = txtUserName.Text;
client.ChannelFactory.Credentials.UserName.Password = txtPassWord.Text;
}
try
{
//just call methods
var jobs = client.Job_List();

foreach (var job in jobs)
{
Console.WriteLine(job.Name);
}
}
catch
{

}