Jobs

Job execution

To execute a job you only have to send a POST request with a job object in the body pointing to the desired entities. There are three ways to reference the job target entities:

Adding an array of target entities

• entities: the same parametrization is applied to all entities

The target array of entities IDs is the easy way to select multiple devices and apply an operation on them. There is a limit in the number of entities in the array, by default the value is 100 . Please consult with your administrator to know the limit configured.

Due to operational issues, the service incorporates a limit in the size of the JSON file. This limit can be configured administratively and by default the limit is set at 300 KBytes. Please consult with your administrator to know the limit configured.

If you need to launch a operation over a large list of entities you can create a Job (POST) setting the active parameter to false and using updating operation (PUT) to append new entities to the target considering the mentioned limit.

Using a previously created tag

You can’t mix target references or filter references with tag references.

If you create a job using tags, there is a previous state, INITIATING, this time is used to create the internal structure of the job, when the platform has finished this internal work, the state of the job will be idle if the tob is not active or scheduled if the job is active

Using filters

You can’t mix filter references with target references or tag references.

You can’t use a previously created filter.

resourceType is an optional query string parameter for this option. This parameter restrict the filter to an specific type of entity, If you include this parameter in the uri of the request only the entities belonging to the selected type will be considered. The available values for this parameter are:

• entity.device, if you want to take into account only devices.
• entity.asset, if you want to take into account only assets.
• entity.commsModule, if you want to take into account only communication modules.
• entity.subscription, if you want to take into account only subscriptions.
• entity.subscriber, if you want to take into account only subscribers.

API specification scheduling

There are two special scheduling modes for a job, both of them are optional.

• scattering
• window

The scattering section is oriented for a job scheduling with protection of a mobile operator cell, if you introduce this section in a job scheduling you have to indicate a operations spread for the job and a strategy factor. This is oriented for using the most time of de planned time of the job trying that the operations don’t fall down a mobile cell.

The window section is oriented for a job scheduling where you want specify a concrete group of days of the week when you want that the job can execute operations and the specific time of the day where you want that de job can execute operations.

The time periods of the window must be multiples of one hour, no interim periods allowed. window examples:

Operation list and operation object and attributes

A job could be executed on a few entities or on thousand of entities if you use a tag. You can retrieve a paginated result list with the operation for each entity, simply sending a GET request using the URL above. The result list have an array of operation objects.

You can apply for the operation results list sending a GET request using the URL above. You must replace {jobId} with the identifier of the operation you want to retrieve.

You can also replace {jobId} with the identifier of the operation you want to retrieve and the pagination settings using {start} and {size} parameters.

Update job

Once the Job is created you can update the job to:

• Modify Job request parameters. You only can mofiy the next parameters
  • active
  • notify
  • callback
  • userNotes
  • schedule.start
  • schedule.stop
• To change (append or remove) entities target list.

A previously created Job can only be updated when this job active parameter is set to false and the job has not started.

When you finish the modification, in the latest PUT call, you have to change active parameter to true to enable the execution is started

As in the POST operation the platform establishes a limit in the JSON size. See creating a Job section for more information about it.

If Job is already started, i.e. IN_PROGRESS status, you have to change active parameter to false to pause the execution, in this state you can’t modify the features of the job

If Job is already paused you have to change active parameter to true to resume the execution

you can’t update the target section of a job based in a filter, for that you have to change active parameter to false and create a new job with the new filter

You can update an already created job sending a PUT request using the URL above. You must replace {jobid} with the identifier of the job you want to update.

Cancel job

Please, pay special attention to the fact that cancelling a job does not imply any roll-back in the already executed steps. So please, be extremely careful when you execute operations.

When you cancel a job, in a first moment the job state will be cancelling. This state will become cancelled when all of its operations are cancelled.

Search for jobs, devices, subscribers, subscriptions operations

Retrieves the list of devices providing a lot of options for:

• Filter (See Specific Filter Fields)

• Order (see Sorting)

• Select Required Fields (see Selecting)

• Summary (see Summary)

It is possible to obtain the results in two different formats, see HTTP Header Options:

JSON Format (Default) CSV Format