Automated Management

The automated management (also known as Batch Jobs) provides a tool to submit the execution of device management operations on a predefined set of target devices and make them run in un-attended manner.

Overview

The automated management feature is composed of the following main concepts:

• Jobs
• Targets
• Steps
• Schedules
• Executions

Targets

Job Targets represent the devices to which the management operations will be submitted; they are identified by the client id of the device. Per each target enlisted, the Targets tab within the Jobs view reports information regarding the status of the processing.

A target is unique for each job and belongs to only one Job. You can specify a target which refers the same device in two separate jobs.

Steps

A job is configured to have one or more Job Steps to be executed on the job targets. Steps can be chained one after the other. During its execution, the job will submit the device management operations defined by the steps following the step sequence defined by the user.

Step Definitions

There is a list of available Job Step Definitions. Each definitions represent a device management operation. Each Job Step Definition has a name which resemble the action and a set of input parameters. Input parameters can be simple types or complex objects and they usually match the API of their Device Management Services.

Executions

After a set of targets and a sequence of Job Steps have been defined, the job can be started. While you can have multiple jobs executing, only one execution at a time can run for the same job instance, .

Schedules

A job can either be started by the user on demand or it can be started according to a Job Schedule. The Job Service will automatically start a job at the defined time according to its schedule.

Creating a Job

A job can be created through the Admin Console application. The prerequisites are the following:

• Batch Job resources assigned to the account: the scope must have at least one Batch Job allowed in the account settings. Number of targets, steps, executions and triggers are not limited.
• A user with job:*:{yourScopeId}:* permissions.

To create a Batch Job first you need to login into an existing account with the prerequisites described above and open the Batch Jobs view.

In here all created Batch Jobs will be listed with some informations on their status.
To create a new Batch Job select the Add button on the toolbar on the top grid.

The name of the job must be unique in the scope. It is advisable to use name that can make an entry easily recognizable.

Adding the targets

The Targets tab is used to manage the targets assigned to a specific job. To add a new target click on the Add button on the toolbar on the bottom grid.

In this dialog you can select all Devices available in the scope or select them one by one. Listed on the grid are the pairs of deviceId and display name of the devices. Selection modes available are the following:

• All
• Select manually
• Select by Tag

Once you selected the desired target devices you can Submit the selection and the targets will be listed on the Targets tab.

• To add a target to the job at least one device has to be registered in the Device Registry.
• The list of Targets can be changed before the job is executed for the first time. After the first run it becomes unmodifiable.

Adding the steps

The Steps tab is used to manage the steps assigned to a specific job. To add a new step click on the Add button on the toolbar on the bottom grid.

In this dialog you can give a unique name to the Step and an optional description.

Using the dropdown menu you can select the type of the Step. Listed are the available job step definitions:

Each job step definition has its own set of property and, by selecting different step definitions the dialog adapts to the properties available.

According to the type of the input parameter, an input field or a text area will be shown. All primitive types, enums and IDs will have an input fields and can be specifies as their string representation. All other types of input parameter will be rendered on text areas and they must be specified according to their XML representation.

📘

For each definition above the actual device associated with the job target should support the device management operation otherwise the execution of the step will fail. ESF/Kura devices implement the operations out of the box. Older versions of Kura/ESF may not support the latest features (e.g. Keystore service or Device activities), check the version installed into your device.

• After submitting the form, a new step will be listed in the tab. Adding one or more step of any kind, will append steps to the list.
• The steps can be modified at any time before the job is executed for the first time. After the first execution they become unmodifiable.

Adding a Scheduled Execution

If you want the job to be executed at a some point in time and/or apply a specific retry policy, you can define a Job Schedule.

Schedules can be managed from the Schedules tab in the Job View. The user can select between the following scheduling types:

• Simple: defining a start and stop date, with a retry interval which can be defined in minutes, hours or days.
• Cron Expression: using a Cron expression that can be bound between a start and end date.
• Device Connect: job will be activated when the device connects to EC connectivity service. This schedule mode helps to cope with scenarios where devices can be disconnected from the EC connectivity service during the job execution.

Execute a Job Manually

The Job Schedule is optional. After targets have been added and steps defined, the job can be started even manually by pressing Start button in the Job view toolbar; the execution will start immediately.

📘

Jobs run in background so you can logout from the console after submission. At any time you can login to the console agin and check the progress of the processing by looking at both the status of the target and the list of executions.

Job Execution

The prerequisites to run a job are the following:

• One or more targets defined.
• One or more job step defined.

Job Targets Status

When the job starts, it will submit the operations defined in the job steps to each device represented by the job targets. During the processing, the status of each target is updated so that the progress of the execution of the steps can be monitored. In the Admin Console, open the Target tab in the Job view. Click on Refresh button to read the last known status.

For a given job target, the job steps will be executed sequentially in the order defined by the Step Index of the job step definition. During the execution, the job target can assume the following status:

• PROCESS_AWAITING
  • Before starting the next step
  • While the operation is in execution by the actual device and the step is waiting the response from the device. Applies when the step definition represents a synchronous operation (e.g. a Configuration Put or a Command Execution).
• AWAITING_COMPLETION
  • While the operation is in execution by the actual device and the step is waiting to receive the completion message (from the device). Applies when the step definition represents an asynchronous operation (e.g. an Activity Submit or a Package Download / Install)
• NOTIFIED_COMPLETION
  • When the device operation is completed and the step received the completion message from the device. Applies when the step definition represents an asynchronous operation (e.g. an Activity Submit or a Package Download / Install).
• PROCESS_OK
  • If the operation of the last step was successful and there are no more steps to be executed on the target
• PROCESS_FAILED
  • If the operation of the last step was un-successful. In this case the processing of the next step, if there's any, will be interrupted.

📘

A common cause for a PROCESS_FAILED is when the device represented by the target is disconnected or disconnects during step execution. Use Job Schedules to define a retry policy.

The the value in the Status column refers to job step represented by the value in the Step Index column.

The job terminates its execution either when:

• There're no more steps to execute, i.e. when each of the job targets are either in status PROCESS_OK with all the steps executed or in status PROCESS_FAILED
• The user interrupted the execution

📘

When job execution is terminated, the job can be run again; it will pick up just the targets for which the execution of the steps is not completed yet and try again from the step next to the last successful one.

Use Job Schedule feature to configure the iteration of executions in a way that best fits for your use case.

Execution Summary

For each job execution, a new entry is added in the Job Execution tab within the Batch Job view. The Job execution summarises:

• The status of the job, i.e. whether it is in-progress or terminated
• The timestamp when the job was started
• The timestamp when the job completed

Each execution has Execution Log that contains the trace of the execution included errors or anomalies that may have occurred during the execution. The log can be useful to debug when a step fails.

📘

Jobs run in background. At any time you can connect to the console and check the progress of the processing by looking at both the status of the target and the list of executions.