General Information

Automate Schedule® implements a RESTful (REpresentational State Transfer) web service on your Automate Schedule server. To access the Automate Schedule web service, you need to use a REST client/library that can construct the URI, header, method (GET, PUT, POST, DELETE), and body of the requests. The base URI for the Automate Schedule web service is "http://myserver:8008/automate-schedule/ws/". By default the web service is turned off. It can be enabled by an administrator in System Settings under Configure Features. Automate Schedule does not need to be restarted to enable/disable this feature.

The web service uses HTTP Basic authentication and therefore does not require cookies, a session identifier, or login pages. For HTTP Basic authentication, the URI is often specified to the client like http://myuser:mypassword@myserver:8008/automate-schedule/ws/. The client then takes that user:password combination out of the URI, encodes it in Base64, and adds a header line similar to: "Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ=". Note: Some clients will not parse the user:password out of the URI and add the header for you. For those clients, you may have to specify the user and password as separate parameters or provide the header line yourself.

If you need a secure connection, you must set up Automate Schedule to use HTTPS (for information on how to do that, see “Converting Automate Schedule to Run in SSL Mode.” After you have set up Automate Schedule to use HTTPS, the web service requests are sent over the encrypted connection. Currently, it’s not possible to have the Automate Schedule web services and normal web UI calls done on separate ports or to mix HTTP/HTTPS. The web service uses the existing web UI connection to the server. If HTTPS is configured for the Automate Schedule server, some clients will require direction on how to handle the secure certificates. Normally, there are two options available:

  • Accept any certificate presented.
  • Specify a local certificate store to check the server’s certificate and reject it if it cannot be verified.

IMPORTANT: Some of the web services described in this topic are only available in the latest version of Automate Schedule. Update your version to be sure you have all the functionality described in the following sections.

Client Demo Examples

Following are several examples of client demos that you can run. Edit the examples as needed for the tasks you’re trying to accomplish. Keep in mind that the object names are case-sensitive.

Note: The examples in this section use a Automate Schedule server located at http://myserver:8008 and a Automate Schedule user called "myuser" with password "mypassword". There is also an agent called "MYAGENT", a job called "MYJOB", a job suite called "MYJOBSUITE", and a member job called "MYMEMBERJOB".

 

curl Examples

# curl creating a new job:
curl -u myuser:mypassword -d @job-example.xml http://myserver:8008/automate-schedule/ws/jobs

# curl releasing a job suite:
curl -u myuser:mypassword http://myserver:8008/automate-schedule/ws/job_suites/MYJOBSUITE/release

# curl holding a job on a server configured for https: while accepting any certificate:
curl -u myuser:mypassword --insecure https://myserver:8008/automate-schedule/ws/jobs/MYJOB/hold

 

wget Examples

# wget creating a new job:
wget --http-user=myuser --http-password=mypassword --post-file=job-example.xml http://myserver:8008/automate-schedule/ws/jobs

# wget releasing an agent's job queue:
wget --http-user=myuser --http-password=mypassword http://myserver:8008/automate-schedule/ws/agents/MYAGENT/release_job_queue

# wget running a job on a server configured for https while accepting any certificate:
wget --http-user=myuser --http-password=mypassword --no-check-certificate https://myserver:8008/automate-schedule/ws/jobs/MYJOB/run

 

Windows PowerShell® 3.0 Examples

# Windows PowerShell 3.0 - hold an agent's job queue:

$auth = 'myuser:mypassword'
$encoded = [System.Text.Encoding]::UTF8.GetBytes($auth)
$encodedpassword = [System.Convert]::ToBase64String($encoded)
$headers = @{"Authorization"="Basic $($encodedpassword)";}
$result = Invoke-RestMethod -uri http://myserver:8008/automate-schedule/ws/agents/MYAGENT/hold_job_queue -Headers $headers -Method Get
echo $result.response.result
echo $result.response.messages.message

 

# Windows PowerShell 3.0 - create a new job:

$auth = 'myuser:mypassword'
$encoded = [System.Text.Encoding]::UTF8.GetBytes($auth)
$encodedpassword = [System.Convert]::ToBase64String($encoded)
$headers = @{"Authorization"="Basic $($encodedpassword)";}
[xml]$myjob = Get-Content job-example.xml
$result = Invoke-RestMethod -uri http://myserver:8008/automate-schedule/ws/jobs -Headers $headers -ContentType "application/xml" -Method Post -Body $myjob
echo $result.response.result
echo $result.response.messages.message

 

# Windows PowerShell 3.0 - restart an agent on a server configured for https while accepting any certificate:

# Note: After you run a series of commands, all HTTPS connections issued from that instance of Windows PowerShell will accept any certificate.

add-type @"
  using System.Net;
  using System.Security.Cryptography.X509Certificates;

  public class IDontCarePolicy : ICertificatePolicy {
    public IDontCarePolicy() {}
    public bool CheckValidationResult(
      ServicePoint sPoint, X509Certificate cert,
      WebRequest wRequest, int certProb) {
      return true;
    }
  }
"@
[System.Net.ServicePointManager]::CertificatePolicy = new-object IDontCarePolicy
$auth = 'myuser:mypassword'
$encoded = [System.Text.Encoding]::UTF8.GetBytes($auth)
$encodedpassword = [System.Convert]::ToBase64String($encoded)
$headers = @{"Authorization"="Basic $($encodedpassword)";}
$result = Invoke-RestMethod -uri https://myserver:8008/automate-schedule/ws/agents/MYAGENT/restart -Headers $headers -Method GET
echo $result.response.result
echo $result.response.messages.message

 

URI Examples

Following are some examples of URIs to make calls to the web service. Given a Automate Schedule server located at http://myserver:8008 and a Automate Schedule user called "myuser" with password "mypassword", following are some examples of URIs to make calls to the web service. The examples have the following:

  • An agent called: MYAGENT.
  • A job called: MYJOB.
  • A job suite called: MYJOBSUITE.
  • A member job called: MYMEMBERJOB.
  • An agent event monitor called: MYAGENTEVENTMONITOR.
  • A notification list called: MYNOTIFICATIONLIST.
  • An IBM i agent environment called: MYIBMIAGTENV.

In the case of POST requests, you must provide an XML representation of the object as the body of the request. See the following section, “XML Notes and Samples,” for tips on creating the XML representations.

Note: If you use the optional parameters when running a job or job suite (see below), the parameters can contain spaces, commas, and HTML tags. However, the combined length of the parameter and its value cannot be more than 2048 characters.

 

Agent actions:

hold job queue (GET request)
http://myserver:8008/automate-schedule/ws/agents/MYAGENT/hold_job_queue

Optional Parameter: queue_name
Note: Without the queue_name parameter, the Agent's Default Job Queue will be held.

release job queue (GET request)
http://myserver:8008/automate-schedule/ws/agents/MYAGENT/release_job_queue

Optional Parameter: queue_name
Note: Without the queue_name parameter, the Agent's Default Job Queue will be released.

restart agent (GET request)
http://myserver:8008/automate-schedule/ws/agents/MYAGENT/restart

stop agent (GET request)
http://myserver:8008/automate-schedule/ws/agents/MYAGENT/stop

list agents (GET request)
http://myserver:8008/automate-schedule/ws/agents/index
optional filters:
name
operating_system

lock Agent (GET request)
http://myserver:8008/automate-schedule/ws/agents/MYAGENT/lock

 unlock Agent (GET request)
http://myserver:8008/automate-schedule/ws/agents/MYAGENT/unlock           

Job actions:

hold job (GET request)
http://myserver:8008/automate-schedule/ws/jobs/MYJOB/hold

release job (GET request)
http://myserver:8008/automate-schedule/ws/jobs/MYJOB/release

run job (GET request)
http://myserver:8008/automate-schedule/ws/jobs/MYJOB/run
Optional Parameters: jobparameter_myname=myvalue, agent_id=1000, skip_reactive=true, clear_reactivity=true, ignore_monitors=true,ignore_conditions=true, run_priority=50, cmd_seq=1, job_name_override=hist_job_name
Example:
http://myserver:8008/automate-schedule/ws/jobs/MYJOB/run?jobparameter_myname=myvalue&jobparameter_a=4
This results in the environment variable myname with a value of myvalue along with another environment variable a with a value of 4 being set in the job that's being requested to run. If set, these parameters override the value of any Automate Schedule variable with the same name in the job run.

http://myserver:8008/automate-schedule/ws/jobs/MYJOB/run?agent_id=1000
It is required that the Job be assigned to an Agent Group and not a single Agent when the agent_id given is the ID of an Agent that belongs to the Agent Group then the Job will run only on the specified Agent.

create job (POST request)
http://myserver:8008/automate-schedule/ws/jobs

delete job (DELETE request)
http://myserver:8008/automate-schedule/ws/jobs/MYJOB

clear all prerequisite statuses for job (GET request)
http://myserver:8008/automate-schedule/ws/jobs/MYJOB/clearallprereqstatuses

list jobs (GET request)
http://myserver:8008/automate-schedule/ws/jobs/index
optional filters:
name
agent_name
agent_id
agent_group_name
agent_group_id

get XML definition of a job (GET request)
http://myserver:8008/automate-schedule/ws/jobs/MYJOB/get
Note: The XML returned contains sufficient information to duplicate the job using the create job web service.

 

Job suite actions:

hold job suite (GET request)
http://myserver:8008/automate-schedule/ws/job_suites/MYJOBSUITE/hold

release job suite (GET request)
http://myserver:8008/automate-schedule/ws/job_suites/MYJOBSUITE/release

run job suite (GET request)
http://myserver:8008/automate-schedule/ws/job_suites/MYJOBSUITE/run
Optional Parameters: jobparameter_myname=myvalue, skip_reactive=true, clear_reactivity=true, ignore_monitors=true, job_name_override=hist_job_name
Example:
http://myserver:8008/automate-schedule/ws/job_suites/MYJOBSUITE/run?jobparameter_myname=myvalue&jobparameter_a=4
This results in the environment variable myname with a value of myvalue along with another environment variable a with a value of 4 being set in every member job that's in the job suite being requested to run. If set, these parameters will override the value of any Automate Schedule variable with the same name in the job run.

create job suite (POST request)
http://myserver:8008/automate-schedule/ws/job_suites

delete job suite (DELETE request)
http://myserver:8008/automate-schedule/ws/job_suites/MYJOBSUITE

skip member job in a job suite (GET request)
http://myserver:8008/automate-schedule/ws/job_suites/MYJOBSUITE/member_jobs/MYMEMBERJOB/skip

include member job in a job suite (GET request)
http://myserver:8008/automate-schedule/ws/job_suites/MYJOBSUITE/member_jobs/MYMEMBERJOB/include

clear all prerequisite statuses for job suite (GET request)
http://server:8008/automate-schedule/ws/jobs/MYJOBSUITE/clearallprereqstatuses

list job suites (GET request)
http://myserver:8008/automate-schedule/ws/job_suites/index
optional filter:
name

get XML definition of a job suite(GET request)
http://myserver:8008/automate-schedule/ws/job_suites/MYJOBSUITE/get
Note: The XML returned contains sufficient information to duplicate the job suite using the create job suite web service.

 

Member job actions:

create member job (POST request)
http://myserver:8008/automate-schedule/ws/member_jobs

delete member job (DELETE request)
http://myserver:8008/automate-schedule/ws/member_jobs/MYMEMBERJOB

skip member job in job suite (GET request)
http://myserver:8008/automate-schedule/scheduler/ws/job_suites/MYJOBSUITE/member_jobs/MYMEMBERJOB/skip

include member job in job suite (GET request)
http://myserver:8008/automate-schedule/scheduler/ws/job_suites/MYJOBSUITE/member_jobs/MYMEMBERJOB/include

list member jobs (GET request)
http://myserver:8008/automate-schedule/ws/member_jobs/index
optional filters:
name
agent_name
agent_id
agent_group_name
agent_group_id
job_suite_name
job_suite_id

get XML definition of a member job (GET request)
http://myserver:8008/automate-schedule/ws/member_jobs/MYMEMBERJOB/get
Note: The XML returned contains sufficient information to duplicate the member job using the create member job web service.

 

All jobs actions:

list all jobs/job suites/member jobs (GET request)
Note: Returns a combined list of all job types.
http://myserver:8008/automate-schedule/ws/jobs/all_jobs
optional filters:
name
agent_name
agent_id
agent_group_name
agent_group_id

 

Agent event monitor actions:

enable agent event monitor (GET request)
http://myserver:8008/automate-schedule/ws/agent_event_monitors/MYAGENTEVENTMONITOR/enable

disable agent event monitor (GET request)
http://myserver:8008/automate-schedule/ws/agent_event_monitors/MYAGENTEVENTMONITOR/disable

 

Job history list actions:

list Job History records (GET request)
Note: The return XML listing is always sorted by server_scheduled_time, newest to oldest.
http://myserver:8008/automate-schedule/ws/job_histories/index

optional filters:
id
job_id
job_name
agent_id
agent_name
agent_group_id
agent_group_name
job_suite_id
job_suite_name
job_suite_history_id
job_status (single char)
scheduled_time_before (yyyy-mm-dd+hh:mm:ss)
scheduled_time_after (yyyy-mm-dd+hh:mm:ss)
server_ended_time_before (yyyy-mm-dd+hh:mm:ss)
server_ended_time_after (yyyy-mm-dd+hh:mm:ss)

optional parameter:
limit (1 to 500), default is to return up to 100 records if limit is not specified

This example gets up to the 10 newest job history records for job MYJOB:
http://myserver:8008/automate-schedule/ws/job_histories/index?job_name=MYJOB&limit=10

This example gets up to 100 records for agent MYAGENT filtered by server scheduled time on July 14 2014 between 1PM and 2PM:
http://myserver:8008/automate-schedule/ws/job_histories/index?agent_name=MYAGENT&scheduled_time_after=2014-07-14+13:00:00&scheduled_time_before=2014-07-14+14:00:00

get Job History record Job Log (GET request)
http://myserver:8008/automate-schedule/ws/job_histories/1000/get_log
In this example the Job History ID is 1000.

Notification list actions:

create notification list (POST request)
http://myserver:8008/automate-schedule/ws/notification_lists

delete notification list (DELETE request)
http://myserver:8008/automate-schedule/ws/notification_lists/MYNOTIFICATIONLIST

list notification lists (GET request)
http://myserver:8008/automate-schedule/ws/notification_lists/index
optional filter:
name

get XML definition of a notification list (GET request)
http://myserver:8008/automate-schedule/ws/notification_lists/MYNOTIFICATIONLIST/get
Note: The XML returned contains sufficient information to duplicate the notification list using the create notification list web service.

 

IBM i agent environment actions:

create IBM i agent environment (POST request)
http://myserver:8008/automate-schedule/ws/ibmi_agent_environments

delete IBM i agent environment (DELETE request)
http://myserver:8008/automate-schedule/ws/ibmi_agent_environments/MYIBMIAGTENV

list IBM i agent environments (GET request)
http://myserver:8008/automate-schedule/ws/ibmi_agent_environments/index

get XML definition of an IBM i agent environment (GET request)
http://myserver:8008/automate-schedule/ws/ibmi_agent_environments/MYIBMIAGTENV/get
Note: The XML returned contains sufficient information to duplicate the IBM i agent environment using the create IBM i agent environment web service.

 

Automate Schedule variable actions:

create Automate Schedule variable (POST request)
http://myserver:8008/automate-schedule/ws/automate-schedule_variables

delete Automate Schedule Variable (DELETE request)
http://myserver:8008/automate-schedule/ws/automate-schedule_variables/MYautomate-scheduleVARIABLE

list Automate Schedule Variables (GET request)
http://myserver:8008/automate-schedule/ws/automate-schedule_variables/index

get XML definition of a Automate Schedule Variable (GET request)
http://myserver:8008/automate-schedule/ws/automate-schedule_variables/MYautomate-scheduleVARIABLE/get
Note: The XML returned contains sufficient information to duplicate the Automate Schedule Variable using the create Automate Schedule Variable web service.

update Automate Schedule Variable (PUT request)
http://myserver:8008/automate-schedule/ws/automate-schedule_variables/MYautomate-scheduleVARIABLE
Note: The <dynamic_type> of a Automate Schedule Variable cannot be changed.

 

Job Queue actions:

hold Cross-Agent Job Queue (GET request)
http://myserver:8008/automate-schedule/ws/job_queues/MYCROSSAGENTJOBQUEUE/hold_job_queue

release Cross-Agent Job Queue (GET request)
http://myserver:8008/automate-schedule/ws/job_queues/MYCROSSAGENTJOBQUEUE/release_job_queue
Note: to hold/release Job Queues belonging to a single Agent see the Agent actions section.

list Job Queues (GET request)
http://myserver:8008/automate-schedule/ws/job_queues/index
optional filters: agent_name, job_queue_type (1=Agent, 2=Cross-Agent  OR Agent/Cross-Agent), name

update Agent type Job Queue (GET request)
http://myserver:8008/automate-schedule/ws/agents/MYAGENT/update_job_queue
parameters: queue_name, hold_on_failure (true/false), limit_active_jobs (true/false), max_active_jobs (0-9999), limiter_enabled (true/false), limiter_minimum_priority (1-99), limiter_max_active (0-9999)

update Cross-Agent type Job Queue (GET request)
http://myserver:8008/automate-schedule/ws/job_queues/MYCROSSAGENTJOBQUEUE/update_job_queue
parameters: hold_on_failure (true/false), limit_active_jobs (true/false), max_active_jobs (0-9999), limiter_enabled (true/false), limiter_minimum_priority (1-99), limiter_max_active (0-9999), limit_active_per_agent (true/false), max_active_per_agent (1-9999)

Forecast Model actions:

 generate Forecast for Forecast Model (GET request)
http://myserver:8008/automate-schedule/ws/forecast_definitions/MYFORECASTDEFINITIONNAME/run_forecast

Server Properties actions:

list the Server Properties (GET request)
http://myserver:8008/automate-schedule/ws/server_properties/index

Command Line Interface Examples

You can skip/include member jobs in a job suite using the command line.

Windows®:

jobservice.bat -configfile=%CREDSFILE% -ssl=any -type=member_jobs -name=%MEMBERJOBNAME% -suite=%JOBSUITENAME% -action=skip

jobservice.bat -configfile=%CREDSFILE% -ssl=any -type=member_jobs -name=%MEMBERJOBNAME% -suite=%JOBSUITENAME% -action=include

UNIX® and Linux®:

./jobservice.sh -configfile=$CREDSFILE -ssl=any -type=member_jobs -name=$MEMBERJOBNAME -suite=$JOBSUITENAME -action=skip

./jobservice.sh -configfile=$CREDSFILE -ssl=any -type=member_jobs -name=$MEMBERJOBNAME -suite=$JOBSUITENAME -action=include

XML Notes and Samples

There are some things to keep in mind as you are writing the XML that you will use when making calls to the web service. Click the links below to see samples:

Job example

Job suite example

Member job example

IBM i job example

As you work with the above files, keep in mind that you must define certain settings (tags) when working with basic jobs, job suites, and member jobs. The required settings are listed below.

Minimum required settings for a basic job:

<!-- GENERAL -->
<!-- SCHEDULE -->
<!-- AGENT ENVIRONMENT -->
<!-- COMMANDS -->

Minimum required settings for a basic job suite:

<!-- GENERAL -->
<!-- SCHEDULE -->
<!-- MEMBER JOBS -->

Minimum required settings for a basic member job:

<!-- GENERAL -->
<!-- AGENT ENVIRONMENT -->
<!-- COMMANDS -->

Minimum required settings for a basic IBM i job:

<!-- GENERAL -->
<!-- SCHEDULE -->
<!-- IBM I AGENT ENVIRONMENT -->
<!-- COMMANDS -->

XML tags that are omitted from the XML document will have values set to the typical default values used in Automate Schedule. XML tags that are included in the XML document, but are empty, will also have values set to the typical default values. If a required XML tag is missing, the server will return an error.

For additional information on writing the XML for the web service calls, see the XML File Notes.

Sample Responses

When using the web service, Automate Schedule returns an XML formatted response. This response contains a <result> tag that indicates "succeed" or "failed". The response can contain one or more <messages>. Each <message> has a <type> and a <content>. Additional information, encoded in XML, may be returned with certain web service requests.

Sample Response 1 - Hold Job

Following is a typical response to a web service request. This is in response to holding a job called "automate-schedule_BACKUP":
GET http://myserver:8008/automate-schedule/ws/jobs/automate-schedule_BACKUP/hold.

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <result>succeed</result>
  <messages>
    <message>
      <type>info</type>
      <content>Job 'automate-schedule_BACKUP' has been held. The job will not be submitted until it is released.</content>
    </message>
  </messages>
</response>

 

Sample Response 2 - Successful Job Run

A successful Run action on a job or job suite returns a section called <job_histories> that has additional information. Following is a response from requesting the same "automate-schedule_BACKUP" job to run:
GET http://myserver:8008/automate-schedule/ws/jobs/automate-schedule_BACKUP/run.

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <result>succeed</result>
  <messages>
    <message>
      <type>info</type>
      <content>Job 'automate-schedule_BACKUP' submitted. Run number is '4451'</content>
    </message>
  </messages>
  <job_histories>
    <job_history>
      <run_number>4451</run_number>
      <agent_name>MYAGENT</agent_name>
      <job_name>automate-schedule_BACKUP</job_name>
    </job_history>
  </job_histories>
</response>

 

Sample Response 3 - View Job History Entry

typical Job History index entry (for an IBM i Job - filtering on the Job History id a.k.a <run_number>):
GET http://myserver:8008/automate-schedule/ws/job_histories/index?id=197366

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <result>succeed</result>
  <records>
    <record>
      <agent_ended_time>2014-06-24 14:11:24 CDT</agent_ended_time>
      <agent_ended_time_utc>1403637084000</agent_ended_time_utc>
      <agent_group_id>0</agent_group_id>
      <agent_group_name></agent_group_name>
      <agent_id>1003</agent_id>
      <agent_name>MY_AGENT_NAME</agent_name>
      <agent_started_time>2014-06-24 14:06:23 CDT</agent_started_time>
      <agent_started_time_utc>1403636783000</agent_started_time_utc>
      <agent_timezone>America/Los_Angeles</agent_timezone>
      <bypass_conditions>false</bypass_conditions>
      <bypass_job_monitors>false</bypass_job_monitors>
      <clear_prereq_status>false</clear_prereq_status>
      <copied_joblog_to_server>false</copied_joblog_to_server>
      <ended_reason_code nil="true"></ended_reason_code>
      <ended_reason_code_translation></ended_reason_code_translation>
      <failed_at_command_sequence>0</failed_at_command_sequence>
      <ibmi_job_name>IBM_I_MJ_2</ibmi_job_name>
      <ibmi_job_number>257733</ibmi_job_number>
      <ibmi_job_user>QPGMR</ibmi_job_user>
      <id>197366</id>
      <initiation_code>6</initiation_code>
      <job_id>1864</job_id>
      <job_name>ibm_i_mj_2</job_name>
      <job_priority>50</job_priority>
      <job_status>C</job_status>
      <job_status_translation>Completed</job_status_translation>
      <job_suite_history_id>197364</job_suite_history_id>
      <job_suite_id>1862</job_suite_id>
      <job_suite_member_instance_id>941</job_suite_member_instance_id>
      <job_suite_member_job_id>1171</job_suite_member_job_id>
      <job_suite_name>ibmi_test</job_suite_name>
      <manually_started>false</manually_started>
      <moved_from_date_time>0</moved_from_date_time>
      <queue_ended_time>2014-06-24 14:05:01 CDT</queue_ended_time>
      <queue_ended_time_utc>1403636701027</queue_ended_time_utc>
      <reactivity_code>0</reactivity_code>
      <restart_child_history_id>0</restart_child_history_id>
      <restart_parent_history_id>0</restart_parent_history_id>
      <retry_next_time>0</retry_next_time>
      <retry_number>0</retry_number>
      <scheduled_time>2014-06-24 14:05:00 CDT</scheduled_time>
      <scheduled_time_utc>1403636700973</scheduled_time_utc>
      <server_ended_time>2014-06-24 14:10:02 CDT</server_ended_time>
      <server_ended_time_utc>1403637002493</server_ended_time_utc>
      <server_initiated_time>2014-06-24 14:05:00 CDT</server_initiated_time>
      <server_initiated_time_utc>1403636700973</server_initiated_time_utc>
      <server_running_time>2014-06-24 14:05:02 CDT</server_running_time>
      <server_running_time_utc>1403636702590</server_running_time_utc>
      <server_submitted_time>2014-06-24 14:05:01 CDT</server_submitted_time>
      <server_submitted_time_utc>1403636701007</server_submitted_time_utc>
      <start_at_command_sequence>1</start_at_command_sequence>
      <termination_data nil="true"></termination_data>
      <timezone_type>S</timezone_type>
      <was_missed>0</was_missed>
    </record>
  </records>
</response>

 

Sample Response 4 - View Agent Entry

typical response for Agents index (filtering on Agent name):
GET http://myserver:8008/automate-schedule/ws/agents/index?name=IBMI_SKYAGENT

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <result>succeed</result>
  <records>
    <record>
      <description>Registered 2014-06-18 13:01 CDT</description>
      <id>1181</id>
      <ip_address>10.10.10.10</ip_address>
      <name>IBMI_SKYAGENT</name>
      <operating_system>OS/400 V6R1M0</operating_system>
      <port_number>7481</port_number>
      <queue_status>Released</queue_status>
    </record>
  </records>
</response>

 

Sample Response 5 - Get Notification List Definition

typical Notification List definition:
GET http://myserver:8008/automate-schedule/ws/notification_lists/MY_NOTIFICATION_LIST/get

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <result>succeed</result>
  <messages>
    <message>
      <type>info</type>
      <requests>
        <request>
          <NotificationList>
            <name>MY_NOTIFICATION_LIST</name>
            <description>test</description>
            <public_list>true</public_list>
            <notification_list_users>
              <notification_list_user>
                <notify_contact_type>User</notify_contact_type>
                <notify_contact_name>MYautomate-scheduleUSER</notify_contact_name>
              </notification_list_user>
              <notification_list_user>
                <notify_contact_type>EmailContact</notify_contact_type>
                <notify_contact>
                  <email_address>my.user@my.company.com</email_address>
                </notify_contact>
              </notification_list_user>
            </notification_list_users>
          </NotificationList>
        </request>
      </requests>
    </message>
  </messages>
</response>

 

Sample Response 6 - Get IBM i Agent Environment Definition

typical IBM i Agent Environment definition:
GET http://myserver:8008/automate-schedule/ws/ibmi_agent_environments/MY_IBM_I_AGENT_ENV/get

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <result>succeed</result>
  <messages>
    <message>
      <type>info</type>
      <requests>
        <request>
          <IbmiAgentEnvironment>
            <name>MY_IBM_I_AGENT_ENV</name>
            <description>has an explicit library list</description>
            <accounting_code>*USRPRF</accounting_code>
            <current_library>*USRPRF</current_library>
            <initial_asp_group>*JOBD</initial_asp_group>
            <job_description>QBATCH</job_description>
            <job_queue>*JOBD</job_queue>
            <job_queue_priority>0</job_queue_priority>
            <library_list>JKRUSE SKYAGENT QSYS QUSRSYS QGPL QTEMP</library_list>
            <message_queue>*NONE</message_queue>
            <message_reply>*JOBD</message_reply>
            <output_queue>*JOBD</output_queue>
            <user_profile>*JOBD</user_profile>
          </IbmiAgentEnvironment>
        </request>
      </requests>
    </message>
  </messages>
</response>

 

Sample Response 7 - Get Job Definition

typical Job definition:
GET http://myserver:8008/automate-schedule/ws/jobs/MYJOB/get

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <result>succeed</result>
  <messages>
    <message>
      <type>info</type>
      <requests>
        <request>
          <Job>
            <name>MYJOB</name>
            <description>test</description>
            <agent_environment_type>AgentEnvironment</agent_environment_type>
            <cond_retry>false</cond_retry>
            <cond_retry_count>0</cond_retry_count>
            <cond_retry_delay>0</cond_retry_delay>
            <condition_fail_status>0</condition_fail_status>
            <conditional>false</conditional>
            <copy_joblog_to_server>false</copy_joblog_to_server>
            <day_count_base_date nil="true"></day_count_base_date>
            <day_count_interval nil="true"></day_count_interval>
            <day_type>A</day_type>
            <default_priority>50</default_priority>
            <email_body_canceled nil="true"></email_body_canceled>
            <email_body_completed nil="true"></email_body_completed>
            <email_body_failed nil="true"></email_body_failed>
            <email_body_latestart nil="true"></email_body_latestart>
            <email_body_member_canceled nil="true"></email_body_member_canceled>
            <email_body_member_failed nil="true"></email_body_member_failed>
            <email_body_overrun nil="true"></email_body_overrun>
            <email_body_retry_wait nil="true"></email_body_retry_wait>
            <email_body_running nil="true"></email_body_running>
            <email_body_skipped nil="true"></email_body_skipped>
            <email_body_submitted nil="true"></email_body_submitted>
            <email_body_underrun nil="true"></email_body_underrun>
            <email_job_log>false</email_job_log>
            <email_subject_canceled nil="true"></email_subject_canceled>
            <email_subject_completed nil="true"></email_subject_completed>
            <email_subject_failed nil="true"></email_subject_failed>
            <email_subject_latestart nil="true"></email_subject_latestart>
            <email_subject_member_canceled nil="true"></email_subject_member_canceled>
            <email_subject_member_failed nil="true"></email_subject_member_failed>
            <email_subject_overrun nil="true"></email_subject_overrun>
            <email_subject_retry_wait nil="true"></email_subject_retry_wait>
            <email_subject_running nil="true"></email_subject_running>
            <email_subject_skipped nil="true"></email_subject_skipped>
            <email_subject_submitted nil="true"></email_subject_submitted>
            <email_subject_underrun nil="true"></email_subject_underrun>
            <generate_skipped_history>false</generate_skipped_history>
            <held_count nil="true"></held_count>
            <hold>0</hold>
            <hold_on_failure>false</hold_on_failure>
            <hold_times nil="true"></hold_times>
            <hold_until nil="true"></hold_until>
            <ibmi_job_name></ibmi_job_name>
            <job_history_purge>false</job_history_purge>
            <job_history_runs_to_keep nil="true"></job_history_runs_to_keep>
            <job_type>0</job_type>
            <late_start_action_selected>false</late_start_action_selected>
            <late_start_end_job>false</late_start_end_job>
            <late_start_monitor_option>0</late_start_monitor_option>
            <late_start_monitor_selected>false</late_start_monitor_selected>
            <late_start_send_email>false</late_start_send_email>
            <late_start_send_snmp_trap>false</late_start_send_snmp_trap>
            <late_start_start_time>0</late_start_start_time>
            <late_start_time nil="true"></late_start_time>
            <member_cancel_notification_list_id nil="true"></member_cancel_notification_list_id>
            <member_fail_notification_list_id nil="true"></member_fail_notification_list_id>
            <missed_action>0</missed_action>
            <non_workday_option>R</non_workday_option>
            <overrun_action_selected>false</overrun_action_selected>
            <overrun_completion_time>0</overrun_completion_time>
            <overrun_end_job>false</overrun_end_job>
            <overrun_monitor_option>0</overrun_monitor_option>
            <overrun_monitor_selected>false</overrun_monitor_selected>
            <overrun_send_email>false</overrun_send_email>
            <overrun_send_snmp_trap>false</overrun_send_snmp_trap>
            <overrun_time nil="true"></overrun_time>
            <schedule_type>UJ</schedule_type>
            <send_cancel_email>false</send_cancel_email>
            <send_cancel_snmp_trap>false</send_cancel_snmp_trap>
            <send_canceled_email_log>false</send_canceled_email_log>
            <send_complete_email>false</send_complete_email>
            <send_complete_email_log>false</send_complete_email_log>
            <send_complete_snmp_trap>false</send_complete_snmp_trap>
            <send_fail_email>false</send_fail_email>
            <send_fail_snmp_trap>false</send_fail_snmp_trap>
            <send_failed_email_log>false</send_failed_email_log>
            <send_member_cancel_email>false</send_member_cancel_email>
            <send_member_cancel_snmp_trap>false</send_member_cancel_snmp_trap>
            <send_member_canceled_email_log>false</send_member_canceled_email_log>
            <send_member_fail_email>false</send_member_fail_email>
            <send_member_fail_snmp_trap>false</send_member_fail_snmp_trap>
            <send_member_failed_email_log>false</send_member_failed_email_log>
            <send_retry_wait_email>false</send_retry_wait_email>
            <send_retry_wait_snmp_trap>false</send_retry_wait_snmp_trap>
            <send_run_email>false</send_run_email>
            <send_run_snmp_trap>false</send_run_snmp_trap>
            <send_skipped_email>false</send_skipped_email>
            <send_skipped_snmp_trap>false</send_skipped_snmp_trap>
            <send_submit_email>false</send_submit_email>
            <send_submit_snmp_trap>false</send_submit_snmp_trap>
            <skip_on_not_completed>false</skip_on_not_completed>
            <system_defaults_for_job_history_purge>true</system_defaults_for_job_history_purge>
            <target_type>Agent</target_type>
            <time_range_end>0</time_range_end>
            <time_range_start>0</time_range_start>
            <timed_interval_base_datetime nil="true"></timed_interval_base_datetime>
            <timed_interval_display_preference nil="true"></timed_interval_display_preference>
            <timed_interval_minutes nil="true"></timed_interval_minutes>
            <timezone_type>S</timezone_type>
            <underrun_action_selected>false</underrun_action_selected>
            <underrun_monitor_selected>false</underrun_monitor_selected>
            <underrun_send_email>false</underrun_send_email>
            <underrun_send_snmp_trap>false</underrun_send_snmp_trap>
            <underrun_time nil="true"></underrun_time>
            <variable_base_date>0</variable_base_date>
            <agent_environment>
              <description nil="true"></description>
              <encrypted_password></encrypted_password>
              <environment_type>1</environment_type>
              <name nil="true"></name>
              <run_type_option>3</run_type_option>
              <user_profile></user_profile>
              <working_path>.</working_path>
              <agent_environment_variables/>
            </agent_environment>
            <command_set>
              <command_set_type>1</command_set_type>
              <description>_private_desc</description>
              <name>_private</name>
              <commands>
                <command>
                  <command_string>sleep 120</command_string>
                  <command_type>0</command_type>
                  <error_handling>true</error_handling>
                  <error_handling_retry>false</error_handling_retry>
                  <line_number>1</line_number>
                  <retries_count>0</retries_count>
                  <wait>true</wait>
                  <wait_count>0</wait_count>
                  <return_code_name>STANDARD</return_code_name>
                </command>
              </commands>
            </command_set>
            <target>
              <hardware_hash>a4c28f5920</hardware_hash>
              <instance_identifier>a7471</instance_identifier>
              <name>MY_AGENT_NAME</name>
              <tag_list>system</tag_list>
            </target>
            <output_distributions/>
            <special_instances/>
            <job_conditions/>
            <basic_runtimes/>
            <day_of_period_runtimes/>
            <day_of_week_runtimes/>
            <day_of_week_runtime_ranges/>
            <job_date_objects/>
            <dependencies/>
            <tag_list>retest</tag_list>
            <calendar_name>STANDARD</calendar_name>
          </Job>
        </request>
      </requests>
    </message>
  </messages>
</response>

 

Sample Response 8 - Automate Schedule Variable Definition

typical Automate Schedule Variable definition:
GET http://myserver:8008/automate-schedule/ws/automate-schedule_variables/MY_automate-schedule_VARIABLE/get

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <result>succeed</result>
  <messages>
    <message>
      <type>info</type>
      <requests>
        <request>
          <automate-scheduleVariable>
            <name>MY_automate-schedule_VARIABLE</name>
            <description>test</description>
            <allow_outside_access>false</allow_outside_access>
            <date_format_code nil="true"></date_format_code>
            <dynamic_type nil="true"></dynamic_type>
            <offset_day_type nil="true"></offset_day_type>
            <offset_days>0</offset_days>
            <static_value>true</static_value>
            <value>my Automate Schedule variable value</value>
          </automate-scheduleVariable>
        </request>
      </requests>
    </message>
  </messages>
</response>

 

Sample Response 9 - Start and Track Job or Job Suite

First make the web service call to run the job "MYJOB".

typical run Job (GET request):
http://myserver:8008/automate-schedule/ws/jobs/MYJOB/run

If the job is successfully started, you'd receive the following XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <result>succeed</result>
  <messages>
    <message>
      <type>info</type>
      <content>Job 'MYJOB' submitted. Run number is '4451'</content>
    </message>
  </messages>
  <job_histories>
    <job_history>
      <run_number>4451</run_number>
      <agent_name>MY_AGENT_NAME</agent_name>
      <job_name>MYJOB</job_name>
    </job_history>
  </job_histories>
</response>

Then, use the <run_number> value (4451 in this sample) to poll for the status of that job run.

typical list Job History records (GET request):
http://myserver:8008/automate-schedule/ws/job_histories/index?id=4451

If the job history record is found, you'd receive the following XML response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <result>succeed</result>
  <records>
    <record>
      <agent_ended_time></agent_ended_time>
      <agent_ended_time_utc>0</agent_ended_time_utc>
      <agent_group_id>0</agent_group_id>
      <agent_group_name></agent_group_name>
      <agent_id>1417</agent_id>
      <agent_name>MY_AGENT_NAME</agent_name>
      <agent_started_time>2014-07-16 15:54:45 CDT</agent_started_time>
      <agent_started_time_utc>1405544085649</agent_started_time_utc>
      <agent_timezone>America/Chicago</agent_timezone>
      <bypass_conditions>false</bypass_conditions>
      <bypass_job_monitors>false</bypass_job_monitors>
      <clear_prereq_status>false</clear_prereq_status>
      <copied_joblog_to_server>false</copied_joblog_to_server>
      <ended_reason_code nil="true"></ended_reason_code>
      <ended_reason_code_translation></ended_reason_code_translation>
      <failed_at_command_sequence>0</failed_at_command_sequence>
      <ibmi_job_name nil="true"></ibmi_job_name>
      <ibmi_job_number nil="true"></ibmi_job_number>
      <ibmi_job_user nil="true"></ibmi_job_user>
      <id>4451</id>
      <initiation_code>2</initiation_code>
      <job_id>200918</job_id>
      <job_name>MYJOB</job_name>
      <job_priority>50</job_priority>
      <job_status>R</job_status>
      <job_status_translation>Running</job_status_translation>
      <job_suite_history_id>0</job_suite_history_id>
      <job_suite_id>0</job_suite_id>
      <job_suite_member_instance_id>0</job_suite_member_instance_id>
      <job_suite_member_job_id>0</job_suite_member_job_id>
      <job_suite_name></job_suite_name>
      <manually_started>true</manually_started>
      <moved_from_date_time>0</moved_from_date_time>
      <queue_ended_time>2014-07-16 15:54:45 CDT</queue_ended_time>
      <queue_ended_time_utc>1405544085500</queue_ended_time_utc>
      <reactivity_code>0</reactivity_code>
      <restart_child_history_id>0</restart_child_history_id>
      <restart_parent_history_id>0</restart_parent_history_id>
      <retry_next_time>0</retry_next_time>
      <retry_number>0</retry_number>
      <scheduled_time>2014-07-16 15:54:45 CDT</scheduled_time>
      <scheduled_time_utc>1405544085338</scheduled_time_utc>
      <server_ended_time></server_ended_time>
      <server_ended_time_utc>0</server_ended_time_utc>
      <server_initiated_time>2014-07-16 15:54:45 CDT</server_initiated_time>
      <server_initiated_time_utc>1405544085338</server_initiated_time_utc>
      <server_running_time>2014-07-16 15:54:45 CDT</server_running_time>
      <server_running_time_utc>1405544085586</server_running_time_utc>
      <server_submitted_time>2014-07-16 15:54:45 CDT</server_submitted_time>
      <server_submitted_time_utc>1405544085452</server_submitted_time_utc>
      <start_at_command_sequence>0</start_at_command_sequence>
      <termination_data></termination_data>
      <timezone_type>S</timezone_type>
      <was_missed>0</was_missed>
    </record>
  </records>
</response>

Use the <job_status_translation> value to determine the current status of the job run. In the example above the status is 'Running'. Continue to make the web service request on the same URL until the <job_status_translation> value turns to one of the terminal status values. Note: Terminal status values you might see are: Completed, Failed, Canceled, and Error. These are the same values that you'd see in the Status column on the Job History page in Automate Schedule.

 


Still have questions? We can help. Submit a case to Technical Support.

Last Modified On: March 11, 2019