Base de Conhecimento

A API de ActivityHistory é responsável por retornar os dados de execução das tarefas de campo. Ela é a forma como o sistema integrado ao uMov.me consegue saber o que aconteceu em campo e poder assim dar prosseguimento aos processos de negócio envolvidos.

Descrição de Histórico

Busca por Lista de Históricos

GET /CenterWeb/api/{$apiKey}/activityHistory.xml

Este recurso permite fazer a busca de históricos de um determinado ambiente.

IMPORTANTE: Utilizando dessa forma, sem utilizar parâmetros de início e fim do histórico, serão mostrados os últimos 7 dias de históricos.

É permitido que você adicione alguns parâmetros na requisição. Os parâmetros são os seguintes:

GET /CenterWeb/api/{$apiKey}/activityHistory.xml?schedule=002

schedule: pesquisar por uma determinada tarefa

GET /CenterWeb/api/{$apiKey}/activityHistory.xml?initialStartTimeOnSystem=2011-10-01%2008:00:00&endStartTimeOnSystem=2011-10-01%2023:59:00:00

Identificar históricos de execução de atividades iniciados entre 2011-10-01 00:00:00 e 2011-10-01 23:59:59

GET /CenterWeb/api/{$apiKey}/activityHistory.xml?initialFinishTimeOnSystem=2011-11-01%2008:00:00&endFinishTimeOnSystem=2011-11-01%2023:59:00:00

Identificar históricos de execução de atividades finalizadas entre 2011-11-01 00:00:00 e 2011-11-01 23:59:59

GET /CenterWeb/api/{$apiKey}/activityHistory.xml?initialStartTimeOnSystem=2011-10-01%2008:00:00&endFinishTimeOnSystem=2011-11-01%2023:59:00:00

Identificar históricos de execução de atividades executadas entre 2011-10-01 00:00:00 e 2011-11-01 23:59:59

GET /CenterWeb/api/{$apiKey}/activityHistory.xml?activity.captureGPS=true&schedule.alternativeIdentifier=teste

Identificar históricos de execução de atividades filtrando os históricos através de atributos das entidades vinculadas

Realizar pesquisas de histórico de execução de atividades utilizando parâmetros pela API uMov.me é simples assim.

Veja um exemplo, do resultado de uma requisição que foi feita em XML:

<result>

<resourceName>activityHistory</resourceName>

<size>1</size>

<entries>

<entry id="100" link="/activityHistory/100.xml"/>

</entries>

</result>

A resposta da requisição será uma mensagem contendo o total de registro retornados e uma lista simples, sem detalhes de cada registro retornado, contendo para cada entrada, Id do registro no uMov.me e o link, que pode ser usado para recuperar os dados específicos deste registro.

Busca de um histórico completo específico (com todos os dados do histórico)

GET /CenterWeb/api/{$apiKey}/activityHistoryHierarchical/{$id}.xml

Esta operação serve para puxar informações de um histórico de execução de atividade do sistema de forma completa. Todos os dados da tarefa e dados coletados são retornadas nessa requisição. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):

<activityHistory>

<id>445</id>

<startTimeOnSystem>2010-10-05 19:30:16</startTimeOnSystem>

<finishTimeOnSystem>2010-10-05 19:30:36</finishTimeOnSystem>

<dataSource>0</dataSource>

<status>true</status>

<executionExportStatus>false</executionExportStatus>

<biExportStatus>false</biExportStatus>

<numberPicturesTaken>2</numberPicturesTaken>

<numberPicturesReceived>1</numberPicturesReceived>

<activity>

<id>9</id>

<description>Entrega Total Realizada</description>

<alternativeIdentifier />

<displayOrder>1</displayOrder>

<minimumAmountPics>0</minimumAmountPics>

<maximumAmountPics>2</maximumAmountPics>

<active>true</active>

<comunicationType>0</comunicationType>

<executionType>1</executionType>

<loopExecution>false</loopExecution>

<takePictures>true</takePictures>

<showsSessionWebForm>false</showsSessionWebForm>

<confirmClose>2</confirmClose>

</activity>

<schedule>

<id>566</id>

<situation>

<id>50</id>

<description>Returned</description>

</situation>

<agent>

<id>38</id>

<name>Entregador 5</name>

<active>false</active>

<login>e5</login>

<centerwebUser>false</centerwebUser>

<mobileUser>true</mobileUser>

<biUser>false</biUser>

<biUserRole>0</biUserRole>

<inputWebAsAnotherUser>false</inputWebAsAnotherUser>

<centerwebUserRole>D</centerwebUserRole>

<validateClient>0</validateClient>

<exportStatus>false</exportStatus>

</agent>

<origin>1</origin>

<hour>16:29</hour>

<date>2010-10-05</date>

<priority>1</priority>

<executionDate>2010-10-05</executionDate>

<alternativeIdentifier />

<executionHour>19:30</executionHour>

<serviceLocal>

<id>6</id>

<alternativeIdentifier />

<description>Trevisan Sao Paulo</description>

<geoCoordinate>-23.566675, -46.6499364</geoCoordinate>

<corporateName>Trevisan Tecnologia Ltda</corporateName>

<streetType>Av.</streetType>

<street>Paulista</street>

<streetNumber>726</streetNumber>

<streetComplement>sala 1707</streetComplement>

<zipCode>99999999</zipCode>

<state>SP</state>

<observation />

<active>true</active>

<origin>1</origin>

<insertDateTime>2010-07-07 20:25:15</insertDateTime>

<lastUpdateDateTime>2010-12-24 14:14:49</lastUpdateDateTime>

</serviceLocal>

<exportSituation>0</exportSituation>

<observation />

<active>true</active>

<activitiesOrigin>1</activitiesOrigin>

<recreateTaskOnPda>false</recreateTaskOnPda>

<urlPublic>

http://center.umov.me/CenterWeb/report/schedule/655521303/1527515806508

</urlPublic>

<scheduleSituationHistories>

<scheduleSituationHistory>

<situation>

<description>Retornada de Campo</description>

</situation>

<lastUpdateDateTime>2016-12-19 11:56:35</lastUpdateDateTime>

</scheduleSituationHistory>

<scheduleSituationHistory>

<situation>

<description>Em Campo</description>

</situation>

<lastUpdateDateTime>2016-12-19 11:56:35</lastUpdateDateTime>

</scheduleSituationHistory>

<scheduleSituationHistory>

<situation>

<description>Pendente de Envio para Campo</description>

</situation>

<lastUpdateDateTime>2016-12-19 11:56:35</lastUpdateDateTime>

</scheduleSituationHistory>

</scheduleSituationHistories>

</schedule>

<sections>

<section>

<id>9</id>

<description>Unica</description>

<order>0</order>

<alternativeIdentifier />

<active>true</active>

<mandatory>1</mandatory>

<useItem>false</useItem>

<findItemsByIdentifier>false</findItemsByIdentifier>

<itemFillMode>0</itemFillMode>

<groupingItemsTypeOnMobile>1</groupingItemsTypeOnMobile>

<items>

<item>

<id>6</id>

<description>Padrão Item</description>

<active>true</active>

<fields>

<field>

<id>23</id>

<mobilePageNumber>1</mobilePageNumber>

<order>0</order>

<nullable>true</nullable>

<unique>false</unique>

<description>Nome Recebedor:</description>

<updatable>true</updatable>

<visible>true</visible>

<tip />

<type>A</type>

<size>25</size>

<active>true</active>

<sourceValue>0</sourceValue>

<showValueInMobile>false</showValueInMobile>

<fieldHistory>

<id>2645</id>

<value>yyyy</value>

<valueForExhibition>yyyy</valueForExhibition>

<status>true</status>

</fieldHistory>

</field>

<field>

<id>24</id>

<mobilePageNumber>1</mobilePageNumber>

<order>1</order>

<nullable>true</nullable>

<unique>false</unique>

<description>Documento Recebedor:</description>

<updatable>true</updatable>

<visible>true</visible>

<tip />

<type>N</type>

<size>15</size>

<active>true</active>

<sourceValue>0</sourceValue>

<showValueInMobile>false</showValueInMobile>

<fieldHistory>

<id>2646</id>

<value>9999</value>

<valueForExhibition>9999</valueForExhibition>

<status>true</status>

</fieldHistory>

</field>

<field>

<id>25</id>

<mobilePageNumber>1</mobilePageNumber>

<order>2</order>

<nullable>true</nullable>

<unique>false</unique>

<description>Tipo Recebedor:</description>

<updatable>true</updatable>

<visible>true</visible>

<tip />

<type>L</type>

<active>true</active>

<listType>U</listType>

<sourceValue>0</sourceValue>

<showValueInMobile>false</showValueInMobile>

<fieldHistory>

<id>2647</id>

<value>1</value>

<valueForExhibition>O Mesmo</valueForExhibition>

<status>true</status>

</fieldHistory>

</field>

</fields>

</item>

</items>

</section>

</sections>

<geoCoordinates>

<geoCoordinate>

<id>1031046</id>

<date>2012-12-27</date>

<hour>161027</hour>

<latitude>0.0</latitude>

<longitude>0.0</longitude>

<type>ON_START_ACTIVITY</type>

<observation>Não foi possível capturar as coordenadas. A pessoa desistiu após tentar novamente 0 vezes.</observation>

<provider/>

<withGps>true</withGps>

<gpsEnabled>true</gpsEnabled>

<networkEnabled>false</networkEnabled>

</geoCoordinate>

<geoCoordinate>

<id>1031045</id>

<date>2012-12-27</date>

<hour>160808</hour>

<latitude>0.0</latitude>

<longitude>0.0</longitude>

<type>ON_START_ACTIVITY</type>

<observation>Não foi possível capturar as coordenadas. A pessoa desistiu após tentar novamente 0 vezes.</observation>

<provider/>

<withGps>true</withGps>

<gpsEnabled>true</gpsEnabled>

<networkEnabled>false</networkEnabled>

</geoCoordinate>

</geoCoordinates>

</activityHistory>

Busca de um histórico específico

GET /CenterWeb/api/{$apiKey}/activityHistory/{$id}.xml

Esta operação serve para puxar informações de um histórico de execução de atividade do sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):

<activityHistory>

<id>563486</id>

<activity>

<id>3146</id>

<description>Atividade</description>

<active>true</active>

<loopExecution>false</loopExecution>

<takePictures>false</takePictures>

</activity>

<schedule>

<id>394748</id>

<origin>4</origin>

<hour>23:31</hour>

<executionHour>23:31</executionHour>

<active>true</active>

<activitiesOrigin>3</activitiesOrigin>

</schedule>

<startTimeOnSystem>2011-10-18 23:31:37</startTimeOnSystem>

<finishTimeOnSystem>2011-10-18 23:31:42</finishTimeOnSystem>

<items>

<activityHistoryItem id="11204373" link="/activityHistoryItem/11204373.xml"/>

</items>

</activityHistory>

Note que ao requisitar as informações de um determinado histórico buscando pelo Id, um conjunto de informações que compõe o histórico de execução são resgatos juntos. Entre as informações estão, dados sobre a atividade, tarefa e uma lista de items que armazenam os valores de execução para os campo da atividade.

Busca de um item de histórico específico

GET /CenterWeb/api/{$apiKey}/activityHistoryItem/{$id}.xml

Através desta operação é possivel obter os dados informados para os campos de uma atividade no momento da execução pelo sistema. Veja o exemplo de retorno de uma entidade abaixo (considerando uma requisição feita em XML):

<activityHistoryItem>

<id>11204373</id>

<section>

<id>10475</id>

<description>Entrega Realizada</description>

<active>true</active>

<mandatory>true</mandatory>

</section>

<item>

<id>38096</id>

<description>Padrão</description>

<active>true</active>

</item>

<sectionField>

<id>38037</id>

<nullable>true</nullable>

<unique>false</unique>

<description>Nota</description>

<updatable>true</updatable>

<visible>true</visible>

<type>N</type>

<size>2</size>

<active>true</active>

</sectionField>

<value>10</value>

</activityHistoryItem>

As informações que compõe um item de histórico de execução são:

Atualização de histórico (Marcar como Exportado)

POST /CenterWeb/api/{$apiKey}/activityHistory/{$id}.xml

Esta operação faz com que o histórico da tarefa seja marcado como exportado. É possível também informar o nome do arquivo ou

lote gerado.

<activityHistory>

<executionExportStatus>true</executionExportStatus>

<exportFileName>Arquivo 12345</exportFileName>

</activityHistory>

Esta operação faz com que o histórico da tarefa seja marcado como não exportado.

<activityHistory>

<executionExportStatus>false</executionExportStatus>

</activityHistory>

Atualização de histórico (Alterar Status de Aprovação)

POST /CenterWeb/api/{$apiKey}/activityHistory/{$id}.xml

Esta operação faz com que o status de aprovação da tarefa seja alterado para APROVADO:

<activityHistory>

<statusApproval>3</statusApproval>

</activityHistory>

Esta operação faz com que o status de aprovação da tarefa seja alterado para REPROVADO:

<activityHistory>

<statusApproval>4</statusApproval>

</activityHistory>

IMPORTANTE:

Só permite gravar histórico com aprovado (statusApproval = 3) ou reprovado (statusApproval = 4) se histórico estiver pendente de aprovação;
Se o histórico estiver como sem necessidade de aprovação, o sistema não permite mudar o status.

Inclusão de histórico

POST /CenterWeb/api/{$apiKey}/schedule/{scheduleId}/activityHistory.xml

POST /CenterWeb/api/{$apiKey}/schedule/alternativeIdentifier/{scheduleIdentifier}/activityHistory.xml

Esta operação permite fazer a criação de um histórico pela API.

O histórico pela api, segue uma estrutura similar ao utilizado pela busca de histórico completo (hierárquico). Nele é informada toda a estrutura do histórico de forma hierárquica (Tarefa > Atividade > Seção > Item > Campo) para que o sistema consiga mapear este registro de forma correta.

A criação do histórico obriga a existência de uma tarefa. Esta tarefa por sua vez tem suas atividades vinculadas, seguidas de seções e campos. Sendo assim para que um histórico seja criado, é necessário que toda a hierarquia de uma execução seja pré-existente no sistema.

Para criação do histórico começamos pela tarefa. Esta tarefa é identificada pela api através das chaves {scheduleId} ou {scheduleIdentifier}, identificada acima na URL de exemplo. Isso demonstra que é possível identificar uma tarefa através de seu id interno do sistema ou pelo identificador alternativo cadastrado.

A tarefa informada na URL deve estar na situação pendente de envio ou em campo. Somente é permitida a inclusão de históricos para atividades que mantem a tarefa em campo. Após a inclusão do histórico, a tarefa passa para a situação Em Campo.

Existem dois tipos de histórico. Um relacionado a algum item ou aqueles utilizados em seções sem items. Para cada caso, existe uma pequena alteração na estrutura do XML que deve ser enviado para a API.

Exemplo de histórico SEM itens:

POST /CenterWeb/api/{$apiKey}/schedule/alternativeIdentifier/tarefa1/activityHistory.xml

<activityHistory>

<activity>

<alternativeIdentifier>atividade1</alternativeIdentifier>

</activity>

<sections>

<section>

<alternativeIdentifier>secao1</alternativeIdentifier>

<fields>

<field>

<alternativeIdentifier>campo1</alternativeIdentifier>

<fieldHistory>

<value>yyyy</value>

<valueForExhibition>yyyy</valueForExhibition>

</fieldHistory>

</field>

<field>

<alternativeIdentifier>campo2</alternativeIdentifier>

<fieldHistory>

<value>9999</value>

<valueForExhibition>9999</valueForExhibition>

</fieldHistory>

</field>

</fields>

</section>

</sections>

</activityHistory>

No exemplo acima está sendo criado um histórico para a tarefa identificada como "tarefa1". Estão sendo preenchidos os campos "campo1" e "campo2" da seção "secao1" na atividade "atividade1". Todos as referências são identificadas utilizando o identificador alternativo.

Exemplo de histórico COM itens:

POST /CenterWeb/api/{$apiKey}/schedule/alternativeIdentifier/tarefa2/activityHistory.xml

<activityHistory>

<activity>

<alternativeIdentifier>atividade2</alternativeIdentifier>

</activity>

<sections>

<section>

<alternativeIdentifier>secao1</alternativeIdentifier>

<items>

<item>

<alternativeIdentifier>item1</alternativeIdentifier>

<fields>

<field>

<alternativeIdentifier>campo1</alternativeIdentifier>

<fieldHistory>

<value>yyyy</value>

<valueForExhibition>yyyy</valueForExhibition>

</fieldHistory>

</field>

<field>

<alternativeIdentifier>campo2</alternativeIdentifier>

<fieldHistory>

<value>9999</value>

<valueForExhibition>9999</valueForExhibition>

</fieldHistory>

</field>

</fields>

</item>

</items>

</section>

</sections>

</activityHistory>

No exemplo acima está sendo criado um histórico para a tarefa identificada como "tarefa2". Estão sendo preenchidos os campos "campo1" e "campo2" do item "item1" da seção "secao1" na atividade "atividade2". Todos as referências são identificadas utilizando o identificador alternativo.

Callback para históricos retornados

O sistema conta com um serviço de callback para notificar automaticamente um histórico recebido na retaguarda para um outro sistema. Isso torna o processo mais ágil, sem a necessidade de fazer requisições de API para consultar se a informação já chegou ou ainda está sendo processada.

Para que o callback funcione de forma adequada, ainda deve ser solicitada a ativação do recurso ao time de suporte. Em breve, estaremos disponibilizando uma interface para que seja possível a ativação do recurso via uMov.Center.

Com o processo ativo, deve ser criado um campo customizável alfanumérico na tarefa. Esse campo deve possuir identificador altenativo = "callback". Dessa forma, ao criar uma tarefa, deve ser informado nesse campo (callback) a URL do seu sistema que irá receber os dados do histórico que estão no uMov.me.

Quando um histórico da tarefa for recebido na retaguarda, com o processo de callback ativo, e com uma URL de callback cadastrada na tarefa, será disparada uma requisição POST para a URL informada contendo uma variável com nome "data" contendo as informações dos históricos recebidos na retaguarda, conforme exemplo listado abaixo:

<schedule>

<alternativeIdentifier>Tarefa XXX</alternativeIdentifier>

<activityHistories>

<activityHistory id="8988776655445393"/>

</activityHistories>

</schedule>

Note que nesse exemplo, é enviado o identificador alternativo da tarefa (Tarefa XXX) e o histórico recebido para a tarefa abaixo com o id="8988776655445393".

Para que a requisição obtenha sucesso, é necessário retornar o status code 200 (OK). Caso o retorno da requisição obtenha um status code diferente de 200(OK), a requisição identificará a chamada com erro.

Importante: O sistema somente irá considerar os históricos recebidos após a data e hora de ativação do recurso e para tarefas que possuem uma URL de callback válida. Além disso, ao disparar a requisição do callback, o sistema marca o histórico como já integrado. Dessa forma, a chamada da API de callback é executada uma única vez por histórico.

Buscando Históricos

Para buscar os dados do histórico, podem ser usados os métodos GET /CenterWeb/api/{$apiKey}/activityHistoryHierarchical/{$id}.xml ou GET /CenterWeb/api/{$apiKey}/activityHistory/{$id}.xml, conforme listado acima.

Observações importantes:

Os valores informados deverão sempre respeitar as informações de tipo, tamanho, etc. dos campos criados pelo sistema. (Ex. apenas números para campos numéricos, etc.);
No caso de campo data o formato esperado do valor deverá ser AAAA-MM-DD;
Não é possível fazer a criação de histórico para campos do tipo foto e multimidia pela API;
Os campos value e valueForExhibition são principalmente usados para casos onde temos campo do tipo lista, nos demais casos (Alfanumérico, Numérico, etc.) você deverá apenas repetir o valor esperado nos dois campos.
As fórmulas de valor e validação para campos, seções e atividades não são executadas na inclusão de histórico via API.
Sistema não valida de itens estão vinculados a seção. Somente valida se item está cadastrado no ambiente.
Não são validados campos ou itens obrigatórios na inclusão via API.
Não é feita a validação de seção e atividades antecessoras.
As coordenadas GPS de execução não podem ser incluídas via API.
Os valores preenchidos em campo lista não são validados para verificar se são válidos conforme o cadastro do campo.

Operações usando HTTP POST

Ao atualizar um histórico você precisa em sua requisição POST identificar os dados do histórico utilizando um parâmetro com o nome data.

Segue um exemplo disparando a requisição a partir de um formulário HTML, onde você precisa trocar {$apiKey} pela chave da sua API e {$id} pelo código do objeto que está sendo modificado. Neste exemplo estamos modificando o status do histórico para exportado. Veja a base do form HTML.

<html>

<form method="POST" action="http://api.umov.me/CenterWeb/api/{$apiKey}/activityHistory/{$id}.xml">

<input type="text" name="data" value="<activityHistory><executionExportStatus>true</executionExportStatus></activityHistory>" />

<input type="submit" />

</form>

</html>

Dados coletados no mobile (ActivityHistory (Histórico de Execução de Atividades))