Tasks are the one-shot unconditional execution of management actions (defined as action scripts) on a set of devices (defined by the scope of the task), as adjusted by execution options. Tasks in this sense are always launched manually by the user and their execution starts immediately.

You are already familiar with how to manage tasks through Bosch IoT Manager's Console. In this page we will go through a typical task-based scenario, programmatically, via Bosch IoT Manager's Java API.

The following examples show you how to create, launch and delete a task, as well as how to subscribe for events:

Access the remote service

Initially, you need to establish a connection to the Mass Management remote service. To do so, refer to the Mass Management Engine-related steps descibed in Remote access to Bosch IoT Manager.

Once the connection is succesfully established, you may continue with concrete interactions with the Mass Management remote service, such as:

Create and launch a task

Creating and launching a task involves the same mechanism as when using the Bosch IoT Manager Console:

Specify the task action script

      Action action = Action.create("groovy", JsonObject.newBuilder().set("groovyScript", "return true;").build());

Specify the task scope and launch the task

When using device scope, you can choose between three scope selection modes to specify the devices of interest:

Id selection - targets one or a number of devices selected via their IDs.
Groovy selection - targets devices via a list script that can be optionally filtered through a filter script.
Group selection - targets a group of devices via their directory. You can refine them through a Groovy script, RQL filter or through tags associated to them.

Learn how to create each of them and then launch the task via the code snippet below:

// Id selection
	Scope scope = DeviceScope.create(IdSelection.newBuilder().deviceIds(Collections.singletonList("your.namespace:device-name")).build());
// Groovy selection 
	scope = DeviceScope.create(GroovySelection.newBuilder().build());
// Group selection
	scope = DeviceScope.create(GroupSelection.newBuilder().build());
	TaskParameters parameters = TaskParameters.newBuilder()
		.name("Task")
		.action(action)
      	.scope(scope)
      	.build();
 
    CompletionStage<Task> taskCompletionStage = mme.launchTask(parameters);

Delete a task

To delete a task, execute:

CompletionStage<Void> delete = task.delete();

Display execution status

To view the execution status of the devices involved in the task, use:

CompletionStage<List<DeviceTaskStatus>> involvedDevices = task.listInvolvedDevices(DeviceExecStatus.State.ANY);

Subscribe for task events

To subscribe for task events, follow the pattern in the following code snippet:

      AtomicReference<StreamHandler> handlerAtomicReference = new AtomicReference<>();
 
      task.subscribeForTaskEvents(Arrays.asList(TaskEvent.Type.values()), new StreamConsumer<TaskEvent>() {
 
        @Override
        public void opened(StreamHandler streamHandler) {
			// It's a good idea to save the stream handler so that later you can unsubscribe.
			handlerAtomicReference.set(streamHandler);
			
			 /*
             * Request count events from the stream/channel. This allows back-pressure for the stream/channel.
             * If the consumer of the events does not want to use back-pressure - call this method with count -1.
             * Note that before this method has been called no events will be send to the consumer.
             */
          	streamHandler.request(-1);
        }
 
        @Override
        public void accept(TaskEvent taskEvent) {
			// on event logic here
        }
 
 
        @Override
        public void close(Throwable throwable) {
          // errors from the remote side are received here before closing of the stream
          // also CancellationException is received if the user has closed the stream manually from the streamHandler received in the accept method
        }
 
      });

Be aware that this way of subscribing may skip the first few events, especially the one concerning the creating of the task. This is why, if you are going to rely on that event, you should launch the task with the launchTask(TaskParameters parameters, StreamConsumer<TaskEvent> consumer) method, so that all events from the beginning of the creation of the specific task can be expected.

Unsubscribe from task events

To unsubscribe from receiving events, close() method of the StreamHandler received in opened() method of your StreamConsumer should be invoked.