Contenido
Grupos de tareas
Servicio: api/v1/tasks/groups/{project id} Formato: JSON
Trae los grupos de tareas asociados a un proyecto específico identificado con su id de proyecto.
El Id de un proyecto se encuentra en la lista de proyectos en usuarios:
Lista de tareas
Servicio: api/v1/tasks Resultado: GeoJSON
Trae la lista de tareas.
Ejemplo: https://api.kontrolid.com/api/v1/tasks
Los links corresponden a:
- detail: Los datos de la tarea. Es similar a la información de arriba sin los links.
- webform: Enlace para ejecución de la tarea desde el formulario web.
- json_data: Si la tarea ya fue completada, trae los datos del formulario diligenciado correspondiente.
Tambien es posible incluir el parámetro ?meta=yes para que incluya los valores de metadatos.
Filtros o Parámetros
Los filtros son pares variable=valor que se especifican en la url adicionando un ? al final de la misma y que filtran los registros que se muestran en la consulta. Cuando se aplican varios filtros, estos se separan con &. Ejemplo: https://api.kontrolid.com/api/v1/tasks?user=api&start=11767
user
El usuario para el cual quiere recuperar las tareas asignadas. En caso de estar vacío se traen todas las tareas correspondientes. Se puede especificar “_unassigned”, para traer las tareas no asignadas:
https://api.kontrolid.com/api/v1/tasks?user=_unassigned
tg_id
Corresponde al id del Grupo de Tareas. Es visible en el mismo api puede revisarlo en el servidor web https://app.kontrolid.com/ -> Tareas –> Grupo de Tareas -> Editar Grupo de Tareas.
period
Restringe las tareas a aquellas programadas dentro de un período de tiempo. Puede tomar los valores de “week” o sea Semanal (Valor por defecto) para mostrar las tareas asignadas hasta una semana, month o sea Mensual para mostrar las tareas asignadas hasta máximo un mes, “all” o sea Todas para traer la totalidad de tareas.
https://api.kontrolid.com/api/v1/tasks?period = week.
start
Recupera los datos desde la llave primaria especificada. La llave primaria es un consecutivo que se asigna a cada registro de tarea asignada. Esta llave es general para todas la tareas, así que deberá conseguirla desde el panel de Gestión de Tareas. Ejemplo, si se quiere recuperar a partir de la llave primaria # 156248.
limit
El número de registros a recuperar
https://api.kontrolid.com/api/v1/tasks?user=api&start=11767&limit=3
sort
Permite ordenar la lista de tareas ya sea por “id” (Por defecto) o por programado “scheduled”.
https://api.kontrolid.com/api/v1/tasks?sort=scheduled
dirn
Dirección del ordenamiento “asc” (Ascendente – Valor por defecto) o “desc” (Descendente)
https://api.kontrolid.com/api/v1/tasks?sort=scheduled&dirn=desc
tz
Zona Horaria. Para que las horas sean establecidas locales. ?tz=America/Bogota
https://api.kontrolid.com/api/v1/tasks?tz=America/Bogota
status
Lista separada por comas de estatus de ejecución de la tarea. Ejemplo. Los valores que puede tomar son: new, accepted, late, unsent, unsubscribed, submitted, rejected, cancelled, deleted, pending, error, blocked. Recuerde especificar periodo, sino sólo visualiza una semana.
https://api.kontrolid.com/api/v1/tasks?status=accepted
Estados de una tarea
Para conocer en detalle los estados de una tarea, ingrese a la sección de gestión de tareas -> Ciclo de vida de tareas (Estados).
Detalle de una tarea
Servicio: api/v1/tasks/{id} Formato: GeoJSON
Trae el detalle de una tarea específica
Ejemplo:
Creación de una tarea
Servicio: api/v1/tasks/ Formato: JSON Método POST
Permite crear una tarea específica. Deberá conocer previamente el grupo de tareas donde se va a asignar, ya que necesitará el tg_id.
Los detalles que puede especificar son los mismos mostrados anteriormente en DETALLES DE UNA TAREA Para enviar una tarea, debe especificar el tipo como x-www-form-urlencoded con key “task”.
Ejemplo en postman:
El siguiente ejemplo carga una tarea manual al grupo de tareas “EJEMPLO” cuyo id es 1707. Survey_ident corresponde al identificador del formulario y assignee_ident es el usuario asignado, From es la fecha/hora de inicio y lon / lat corresponde a la ubicación GPS donde se debe efectuar la tarea.
Ejemplo 2:
Este ejemplo es más sofisticado y construye la tarea precargando datos iniciales.
En este caso primero se hizo la creación de tareas basado en datos existentes y se creó una primera tarea para validar los datos de sus construcción en el API.
Se hizo la consulta del API y siguiendo el link del detalle: detail, se accede a los datos necesarios para la construcción de las tareas. Como es una precarga de datos, es necesario tener los datos del identificador de la instancia para indicar se van a reemplazar y dejar vacío el id de la tarea para que vaya creando cada vez una nueva.
Así queda para subir con postman por ejemplo:
preserveInitialData
Al actualizar una tarea existente que ya tiene datos iniciales, puede optar por no incluir initial_data y establecer este parámetro para conservar los datos existentes o borrarlos. Establezcalo en true o false
