Skip to end of metadata
Go to start of metadata

Scope

  • The JobScheduler Web Service can be used by any client program or job that has to access JobScheduler objects for operations such as adding an order to a job chain.
  • The REST Web Service is a replacement for the XML Interface. and require authentication and authorization.
  • A system administrator manages the permissions required to carry out the operations used by the REST Web Services. More information about how this can be done is available with the Authentication and Authorization - Configuration article. The default setting is 20 minutes.

Usage

  • The REST Web Service is called by using an HTTP client.
  • The following REST web service requests are supported:
    • URL joc/api/security/login
      • The first operation of a client should be call to this URL in order to authenticate and to retrieve an access token.
      • A valid account and password have to be provided by the client for HTTP authentication. The account and permissions for the command(s) to be executed are configured with the shiro.ini configuration file. See the Authentication and Authorization - Configuration article and the example api_user configuration for further information.
      • Use the joc/api/security/joc_cockpit_permissions URL to retrieve the permissions for the current user.
    • URL joc/api/jobscheduler/command 
      • Subsequent XML Commands can be sent by use of this URL. 
      • The XML command is added to the body of the web service request.
      • The JobScheduler REST Web Services will return the respective XML Response.
    • URL joc/api/security/logout
      • The last operation of a client should be a call to this URL in order to logout from the web service
  • Requirements
    • All REST web service requests should use an HTTP POST operation.
    • The current session will be invalidated and a re-login will be required if the idle timeout between two web service requests is exceeded. The idle timeout can be configured in the [main] section of the shiro.ini file (see Authentication and Authorization - Configuration for more information).

Complete List of Permissions

The following table provides more information about all of the permissions that can be set to allow an API user to address the JobScheduler REST Web Services.

PermissionReference to XML InterfaceDescription
sos:products:commands:jobscheduler_master:view:status<show_state/>Retrieves status information about a JobScheduler Master
sos:products:commands:jobscheduler_master:view:parameter

<params.get/>

<param.get name="..."/>

Shows parameters from ./config/scheduler.xml
sos:products:commands:jobscheduler_master:view:calendar<show_calendar/>Shows the planned start times
sos:products:commands:jobscheduler_master:execute:restart:terminate<terminate restart="yes"/>Terminates and restarts a JobScheduler Master
sos:products:commands:jobscheduler_master:execute:restart:abort<modify_spooler cmd="abort_immediately_and_restart"/> Aborts and restarts a JobScheduler Master
sos:products:commands:jobscheduler_master:execute:pause<modify_spooler cmd="pause"/>Pauses a JobScheduler Master
sos:products:commands:jobscheduler_master:execute:continue<modify_spooler cmd="continue"/> Continues operation of the JobScheduler Master after pausing
sos:products:commands:jobscheduler_master:execute:terminate<terminate/>Terminates a JobScheduler Master
sos:products:commands:jobscheduler_master:execute:abort<modify_spooler cmd="abort_immediately"/>Aborts a JobScheduler Master
sos:products:commands:jobscheduler_master:execute:stop<modify_spooler cmd="stop"/>Stops any running tasks in a JobScheduler Master
sos:products:commands:jobscheduler_master:manage_categories<scheduler_log.log_categories.set/>
<scheduler_log.log_categories.show/> 

<scheduler_log.log_categories.reset/>  
Activates, retrieves and resets log categories
sos:products:commands:jobscheduler_master_cluster:execute:terminate_fail_safe

<modify_spooler cmd="continue_exclusive_operation"/>

Terminates the active JobScheduler cluster member and activates a passive cluster member for fail-over
sos:products:commands:jobscheduler_master_cluster:execute:restart<terminate restart="yes" all_schedulers="yes"/>Terminates and restarts all JobScheduler cluster members
sos:products:commands:jobscheduler_master_cluster:execute:terminate<terminate all_schedulers="yes"/>Terminates all JobScheduler cluster members
sos:products:commands:history:view<show_history/>Retrieve the JobScheduler history
sos:products:commands:order:view:status<show_order/>Retrieve order status information
sos:products:commands:order:change:start_and_end_node<modify_order state="..." end_state="..."/>Modifies the starting and ending states of an order
sos:products:commands:order:change:time_for_adhoc_orders<modify_order><run_time/></modify_order>Modifies the run-time of a temporary ad hoc order
sos:products:commands:order:change:parameter<modify_order><params><param name="..." value="..."/></params></modify_order>Modifies order parameters
sos:products:commands:order:change:run_time<modify_order><run_time/></modify_order>Modifies the run-time of a permanent order
sos:products:commands:order:change:state<modify_order state="..."/>Modifies an order's state
sos:products:commands:order:change:other<modify_order/>Modifies any remaining order attributes not covered by other permissions
sos:products:commands:order:change:hot_folder<modify_hot_folder><order/></modify_hot_folder>Updates an order in the JobScheduler Master ./config/live directory
sos:products:commands:order:execute:start<modfiy_order at="now"/>Causes an immediate start of the order
sos:products:commands:order:execute:update<modify_order/>Updates order attributes
sos:products:commands:order:execute:suspend<modify_order suspended="yes"/>Suspends an order
sos:products:commands:order:execute:resume<modify_order suspended="no"/>Continues a previously suspended order
sos:products:commands:order:execute:reset<modify_order action="reset"/>Resets an order
sos:products:commands:order:execute:remove_setback<modify_order setback="no"/>Removes a setback setting for an order
sos:products:commands:order:delete<remove_order/>Removes a temporary ad hoc order from the JobScheduler Master
sos:products:commands:job_chain:view:status<show_state/>Retrieves status information about a job chain
sos:products:commands:job_chain:execute:stop<job_chain.modify state="stopped"/>Stops a job chain
sos:products:commands:job_chain:execute:unstop<job_chain.modify state="running"/>Continues a previously stopped job chain
sos:products:commands:job_chain:execute:add_order<add_order/> Add a temporary ad hoc order to a job chain
sos:products:commands:job_chain:execute:skip_jobchain_node<job_chain_node.modify action="next_state"/>Skips a job chain node
sos:products:commands:job_chain:execute:process_jobchain_node<job_chain_node.modify action="process"/>Continues processing of a job chain node that has previously been skipped or stopped
sos:products:commands:job_chain:execute:stop_jobchain_node<job_chain_node.modify action="stop"/>Stops a job chain node
sos:products:commands:job_chain:change:hot_folder<modify_hot_folder><job_chain/></modify_hot_folder>Updates a job chain in the JobScheduler Master ./config/live directory
sos:products:commands:job_chain:remove<remove_job_chain/>Removes a job chain
sos:products:commands:job:view:status<show_job/>Retrieves status information about a job
sos:products:commands:job:change:run_time<modify_job><run_time/></modify_job>Modifies the run-time of a job
sos:products:commands:job:change:hot_folder<modify_hot_folder><job/></modify_hot_folder>Updates a job in the JobScheduler Master ./config/live directory
sos:products:commands:job:execute:start<start_job/>Starts a job
sos:products:commands:job:execute:stop<modify_job cmd="stop"/>Stops a job
sos:products:commands:job:execute:unstop<modify_job cmd="unstop"/>Unstops a previously stopped job
sos:products:commands:job:execute:terminate<modify_job cmd="end"/>Terminates a job
sos:products:commands:job:execute:kill<kill_task/>Kills a task that is running for the job
sos:products:commands:job:execute:end_all_tasks<kill_task immediately="yes" timeout="never"/>  Sends all running tasks for a job a SIGTERM signal
sos:products:commands:job:execute:suspend_all_tasks<modify_job cmd="suspend"/>Suspends all running tasks for a job
sos:products:commands:job:execute:continue_all_tasks<modify_job cmd="continue"/>Continues all previously suspended tasks for a job
sos:products:commands:process_class:view:status<show_state/>Retrieves status information about process classes
sos:products:commands:process_class:edit:change<process_class/>Modifies a process class
sos:products:commands:process_class:edit:remove<process_class.remove/>Removes a process class
sos:products:commands:process_class:modify_hot_folder<modify_hot_folder><process_class/></modify_hot_folder>Updates a process class in the JobScheduler Master ./config/live directory
sos:products:commands:schedule:view:status<show_state/>Retrieves status information about schedules
sos:products:commands:schedule:add_substitute<modify_hot_folder><schedule substitute="..."/></modify_hot_folder>Assigns a substitute schedule to an existing schedule
sos:products:commands:schedule:remove<schedule.remove/>Removes a schedule
sos:products:commands:schedule:modify_hot_folder<modify_hot_folder><schedule/></modify_hot_folder>Updates a schedule in the JobScheduler Master ./config/live directory
sos:products:commands:lock:view:status<show_state/>Retrieves status information about locks
sos:products:commands:lock:edit:change<lock/>Modifies a lock
sos:products:commands:lock:remove<lock.remove/>Removes a lock

Examples

Allow orders to be viewed and executed

Allow orders to be viewed and executed, but not changed
sos:products:commands:order:view, \
sos:products:commands:order:execute, \

Allow all order operations except changing and removing orders

Allow orders to be viewed and executed, but not changed
sos:products:commands:order, \
-sos:products:commands:order:change, \
-sos:products:commands:order:remove, \


Retrieve permissions for the current user

The answer to the joc/api/security/joc_cockpit_permissions request is a JSON object.

The valueOf(permission) function will be evaluated to true/false indicating if the permission is granted.

If the user is assigned a role that includes the permissions specified in brackets then the permission will be granted.

joc/api/security/joc_cockpit_permissions
{
  "isAuthenticated": true,
  "user": "SOS01",
  "accessToken": "dfd96e2c-ef7f-4158-acf3-1af98d4407c4",
  "JobschedulerMaster": {
    "view": {
      "status": valueOf(sos:products:joc_cockpit:jobscheduler_master:view:status),
      "mainlog": valueOf(sos:products:joc_cockpit:jobscheduler_master:view:mainlog)
    },
    "pause": valueOf(sos:products:joc_cockpit:jobscheduler_master:pause),
    "continue": valueOf(sos:products:joc_cockpit:jobscheduler_master:continue),
    "restart": {
      "terminate": valueOf(sos:products:joc_cockpit:jobscheduler_master:restart:terminate),
      "abort": valueOf(sos:products:joc_cockpit:jobscheduler_master:restart:abort)
    },
    "terminate": valueOf(sos:products:joc_cockpit:jobscheduler_master:terminate),
    "abort": valueOf(sos:products:joc_cockpit:jobscheduler_master:abort),
    "manageCategories": sos:products:joc_cockpit:jobscheduler_master:manage_categories)
  },
  "JobschedulerMasterCluster": {
    "view": {
      "clusterStatus": valueOf(sos:products:joc_cockpit:jobscheduler_master_cluster:view:cluster_status)
    },
    "terminateFailSafe": valueOf(sos:products:joc_cockpit:jobscheduler_master_cluster:terminate_fail_safe),
    "restart": valueOf(sos:products:joc_cockpit:jobscheduler_master_cluster:terminate_cluster_member:restart),
    "terminate": valueOf(sos:products:joc_cockpit:jobscheduler_master_cluster:terminate_cluster_member:terminate)
  },
  "JobschedulerUniversalAgent": {
    "view": {
      "status": valueOf(sos:products:joc_cockpit:jobscheduler_universal_agent:view:status)
    },
    "terminate": valueOf(sos:products:joc_cockpit:jobscheduler_universal_agent:terminate),
    "abort": valueOf(sos:products:joc_cockpit:jobscheduler_universal_agent:abort),
    "restart": {
      "terminate": valueOf(sos:products:joc_cockpit:jobscheduler_universal_agent:restart:terminate),
      "abort": valueOf(sos:products:joc_cockpit:jobscheduler_universal_agent:restart:abort)
    }
  },
  "DailyPlan": {
    "view": {
      "status": valueOf(sos:products:joc_cockpit:daily_plan:view_status)
    }
  },
  "History": {
    "view": valueOf(sos:products:joc_cockpit:history:view)
  },
  "Order": {
    "view": {
      "configuration": valueOf(sos:products:joc_cockpit:order:view:configuration),
      "orderLog": valueOf(sos:products:joc_cockpit:order:view:order_log),
      "status": valueOf(sos:products:joc_cockpit:order:view:status)
    },
    "change": {
      "startAndEndNode": valueOf(sos:products:joc_cockpit:order:change:start_and_end_node),
      "timeForAdhocOrder": valueOf(sos:products:joc_cockpit:order:change:time_for_adhoc_orders),
      "parameter": valueOf(sos:products:joc_cockpit:order:change:parameter)
    },
    "start": valueOf(sos:products:joc_cockpit:order:start),
    "update": valueOf(sos:products:joc_cockpit:order:update),
    "suspend": valueOf(sos:products:joc_cockpit:order:suspend),
    "resume": valueOf(sos:products:joc_cockpit:order:resume),
    "delete": {
      "temporary": valueOf(sos:products:joc_cockpit:order:delete:temporary)
      "permanent": valueOf(sos:products:joc_cockpit:order:delete:permanent)
      }
    },
    "removeSetback": valueOf(sos:products:joc_cockpit:order:remove_setback)
  },
  "JobChain": {
    "view": {
      "configuration": valueOf(sos:products:joc_cockpit:job_chain:view:configuration),
      "history": valueOf(sos:products:joc_cockpit:job_chain:view:history),
      "status": valueOf(sos:products:joc_cockpit:job_chain:view:status)
    },
    "stop": valueOf(sos:products:joc_cockpit:job_chain:stop),
    "unstop": valueOf(sos:products:joc_cockpit:job_chain:unstop),
    "addOrder": valueOf(sos:products:joc_cockpit:job_chain:add_order),
    "skipJobChainNode": valueOf(sos:products:joc_cockpit:job_chain:skip_jobchain_node),
    "unskipJobChainNode": valueOf(sos:products:joc_cockpit:job_chain:unskip_jobchain_node),
    "stopJobChainNode": valueOf(sos:products:joc_cockpit:job_chain:stop_jobchain_node),
    "unstopJobChainNode": valueOf(sos:products:joc_cockpit:job_chain:unstop_jobchain_node)
  },
  "Job": {
    "view": {
      "status": valueOf(sos:products:joc_cockpit:job:view:status),
      "taskLog": valueOf(sos:products:joc_cockpit:job:view:task_log),
      "configuration": valueOf(sos:products:joc_cockpit:job:view:configuration),
      "history": valueOf(sos:products:joc_cockpit:job:view:history)
    },
    "start": {
      "task": valueOf(sos:products:joc_cockpit:job:start:task),
      "taskImmediately": valueOf(sos:products:joc_cockpit:job:start:task_immediately)
    },
    "stop": valueOf(sos:products:joc_cockpit:job:stop),
    "unstop": valueOf(sos:products:joc_cockpit:job:unstop),
    "terminate": valueOf(sos:products:joc_cockpit:job:terminate),
    "kill": valueOf(sos:products:joc_cockpit:job:kill)
  },
  "ProcessClass": {
    "view": {
      "status": valueOf(sos:products:joc_cockpit:process_class:view:status),
      "configuration": valueOf(sos:products:joc_cockpit:process_class:view:configuration)
    }
  },
  "Schedule": {
    "view": {
      "status": valueOf(sos:products:joc_cockpit:schedule:view:status),
      "configuration": valueOf(sos:products:joc_cockpit:schedule:view:configuration)
    },
    "edit": valueOf(sos:products:joc_cockpit:schedule:edit),
    "addSubstitute": valueOf(sos:products:joc_cockpit:schedule:add_substitute)
  },
  "Lock": {
    "view": {
      "status": valueOf(sos:products:joc_cockpit:lock:view:status),
      "configuration": valueOf(sos:products:joc_cockpit:lock:view:configuration)
    }
  },
  "Event": {
    "view": {
      "status": valueOf(sos:products:joc_cockpit:event:view:status)
    },
    "delete": valueOf(sos:products:joc_cockpit:event:delete)
  },
  "EventAction": {
    "view": {
      "status": valueOf(sos:products:joc_cockpit:event_action:view:status)
    },
    "createEventsManually": valueOf(sos:products:joc_cockpit:event_action:create_event_manually)
  },
  "HolidayCalendar": {
    "view": {
      "status": valueOf(sos:products:joc_cockpit:holiday_calendar:view:status)
    }
  },
  "MaintenanceWindow": {
    "view": {
      "status": valueOf(sos:products:joc_cockpit:maintenance_window:view:status)
    },
    "enableDisableMaintenanceWindow": valueOf(sos:products:joc_cockpit:maintenance_window:enable_disable_mainenance_window)
  },
  "SOSPermissionRoles": {
    "SOSPermissionRole": [
      "application_manager"
    ]
  }
}

References

 

 

Write a comment…