---
# System prepended metadata

title: HIP Job API

---

HIP Job API
====

[TOC]

# Roles
- job management
    - job
    - job execution
- job event management
    - mqtt publish to topics(/job/notify, /job/notify-next)

```sequence
request->**job_event_mgt**: device_list
Note right of **job_event_mgt**: break to smaller task(by device)
**job_event_mgt**->SQS: put task in queue
SQS->lambda: trigger lambda
lambda->DB: query job_exe
Note right of lambda: process job notify logic
lambda->Redis: acquire lock(by device)
Note right of lambda: await and have expiration time
lambda->Redis: get temp data by key(topic)
Note right of lambda: compare with temp data
lambda->Redis: if differenct then set temp data
lambda->IoT: pub message
```

- device management
    - update device attribute
    - create dynamic group
# API
## query job
- Rest API
    - GET {version}/{domain}/job
    - GET {version}/{domain}/{device_id}/job

```sequence
user->handler: query job
handler->job_mgt: query job
Note right of job_mgt: query job
job_mgt->handler: resp
handler->user: resp
```

## create job
- Rest API
    - POST {version}/{domain}/job
    - POST {version}/{domain}/{device_id}/job
    
```sequence
user->handler:create job
handler->job_mgt: create job
Note right of job_mgt: create job
handler->**job_group_sentry**: send filter_string
handler->user: resp
```
### job group sentry

```sequence
request->handler: filter_string or None
handler->job_mgt: query_filter_string_by_domain
handler->device_mgt: query_devices_with_filter_string
device_mgt->handler: device_list
handler->device_mgt: create relations
Note right of device_mgt: create relations
handler->job_mgt: create job_exe
Note right of job_mgt: create job_exe
handler->**job_event_mgt**: send with device_ids
Note right of **job_event_mgt**: send event to topics
```


## delete job
- Rest API
    - DELETE {version}/{domain}/job

```sequence
user->handler: delete job
handler->job_mgt: delete job
Note right of job_mgt: delete job and related job_exe
Note right of job_mgt: delete device group
job_mgt->handler: resp
handler->**job_event_mgt**: send with device_ids
Note right of **job_event_mgt**: send event to topics
handler->user: resp
```

## device join the device group

```sequence
device->handler: update device
handler->device_mgt: update device
device_mgt->**job_group_sentry**: notify device changed
handler->device: resp
```

## query job execution
- Rest API
    - GET {version}/{domain}/{device_id}/job/{job_id}

```sequence
user->handler: query job_exe 
handler->job_mgt: query job_exe
job_mgt->handler: resp
handler->user:resp
```


## update job execution status(in_progress, cancel)
- Rest API
    - PUT {version}/{domain}/{device_id}/job/{job_id}

```sequence
user->handler: update job_exe
handler->job_mgt: update job_exe
job_mgt->**job_event_mgt**: send with job_id and devices_ids
job_mgt->handler: resp
handler->user: resp
```

## NotifyPendingJobsChange
It will notify only when:
- New job enqueued.
- Job changed to terminal state.
- MQTT
    - {version}/{domain}/{device_id}/job/notify
```sequence
device->handler: update job_exe
handler->job_mgt: update job_exe
job_mgt->**job_event_mgt**: send with device_ids
```

## GetPendingJobs
- MQTT
    - {version}/{domain}/{device_id}/job/get
```sequence
device->handler: query job list
handler->job_mgt: query job list
job_mgt->handler: jobs
handler->device: mqtt_pub
```

## DescribeJobExecution
- MQTT
    - {version}/{domain}/{device_id}/job/{job_id}/get
```sequence
device->handler: query job_exe
handler->job_mgt: query job_exe
job_mgt->handler: job_exe
handler->device: mqtt_pub
```

## UpdateJobExecution
- MQTT
    - {version}/{domain}/{device_id}/job/{job_id}/update
```sequence
device->handler: update job_exe
handler->job_mgt: update job_exe
job_mgt->**job_event_mgt**: send with device_ids
```



# Table
![](https://i.imgur.com/fwHzMdj.png)
