REST API de Monitoramento (versão 1)

Para melhor entender quando se utiliza cada operação apresentada nesta página, iniciaremos apresentando cenários de uso e em seguida as operações são apresentadas em detalhes.

Cenário de uso: monitoramento por sistema externo sem uso de identificador amigável

Neste cenário um sistema externo utiliza o monitoramento do Lumis Portal, sem utilização do campo de identificador amigável do usuário monitorado. Neste caso o sistema externo usará o identificador do usuário monitorado, possivelmente armazenando-o associado ao usuário do sistema, como forma de poder referenciar o mesmo usuário monitorado quando necessário.

Um uso básico neste cenário seria:

1. Um usuário inicia sua interação com o sistema externo. Se o sistema ainda não possui um identificador de usuário monitorado para este usuário, ele irá gerá-lo executando POST .../monitor-users, opcionalmente incluindo informações conhecidas sobre o usuário para serem armazenadas no monitoramento do Lumis Portal. A chamada para esta operação irá retornar o identificador do usuário monitorado que o sistema externo deverá armazenar de forma que possa reutilizá-lo sempre que quiser referenciar este mesmo usuário.
2. Quando o sistema externo quiser armazenar informação sobre alguma ação feita pelo usuário, poderá utilizar a operação POST .../events/{id}/data, repassando como valor da propriedade lum_user.id o identificador do usuário monitorado (assumindo que o evento sendo coletado possui o campo correspondente).
3. Quando o sistema externo quiser atualizar alguma informação sobre este usuário, poderá utilizar a operação PATCH .../monitor-users/{id}.

Cenário de uso: monitoramento por sistema externo com uso de identificador amigável

Neste cenário um sistema externo utiliza o monitoramento do Lumis Portal, utiliza sua própria forma de identificar um usuário como identificador amigável no usuário monitorado do Lumis Portal.

Por exemplo, suponhamos que o sistema possui seus usuários cadastrados em um Active Directory, e utiliza como forma de identificar o usuário o seu login. Estes usuários podem ser importados para também existirem no Lumis Portal ou não. Caso sejam importados, neste exemplo a configuração de identificador amigável de usuários monitorados deve ser configurada para o identificador amigável de usuários monitorados que correspondem a usuários do Lumis Portal ser seu login (assumindo que está no mesmo formato do login do sistema externo), para ser consistente com a forma que o sistema externo irá gerar esses identificadores.

Neste caso o sistema externo não precisa persistir de forma permanente o identificador do usuário monitorado associado ao seu usuário, pois poderá recuperá-lo a partir do identificador amigável que foi definido pelo próprio sistema. Ele precisará manter o identificador do usuário monitorado em caso em que ainda não tem conhecimento de qual seu usuário está efetuando acesso (por exemplo, um website que permite acesso sem autenticação) e manter temporariamente no caso de usuário conhecido para evitar ter que chamar sempre a operação para recuperar o identificador a partir do identificador amigável (em ambos os casos, em uma aplicação web, é comum para este rastreio armazenar o identificador em web storage, cookie ou sessão).

Um uso básico neste cenário seria:

1. Um usuário inicia sua interação com o sistema externo. Se o sistema ainda não possui um identificador de usuário monitorado para este usuário, ele irá gerá-lo executando o POST .../monitor-users, opcionalmente incluindo informações conhecidas sobre o usuário para serem armazenadas no monitoramento do Lumis Portal. Caso já se saiba o identificador amigável deste usuário (por exemplo, já foi autenticado), o identificador amigável deve ser passado nesta chamada para que seja utilizado o usuário monitorado correspondente.
2. Quando o sistema externo quiser armazenar informação sobre alguma ação feita pelo usuário, poderá utilizar a operação POST .../events/{id}/data, repassando como valor da propriedade lum_user.id o identificador do usuário monitorado (assumindo que o evento sendo coletado possui o campo correspondente).
3. Quando o sistema externo quiser atualizar alguma informação sobre este usuário, poderá utilizar a operação PATCH .../monitor-users/{id}.
4. Quando o usuário for reconhecido pelo sistema externo de forma que ele passe a saber o identificador amigável antes não conhecido (por exemplo, ao efetuar login), deve ser utilizada a operação POST .../monitor-users/{id}/identify, que fará atualização dos usuários monitorados correspondentes se necessário e retornará o identificador de usuário monitorado que deve ser usado para representar o usuário com o identificador amigável especificado.

POST /lumis/api/rest/lumis/monitor/v1/monitor-users

Adiciona um usuário monitorado ou atualiza um usuário monitorado com um friendlyId especificado.

Cabeçalhos de Requisição

Esta operação requer cabeçalhos na requisição compatíveis com:

Corpo da Requisição

O corpo da requisição deve ser um objeto JSON com as propriedades listadas abaixo:

Resposta de Sucesso

Quando a operação é bem sucedida, a resposta conterá um objeto JSON informação sobre a ação executada e o identificador do usuário monitorado criado ou atualizado.

Resposta de Erro

Esta operação responde como erro o objeto JSON padrão de erro.

Exemplo de Requisição

POST /lumis/api/rest/lumis/monitor/v1/monitor-users HTTP/1.1
Accept: application/json
Content-Type: application/json
(... outros cabeçalhos ...)

{
	"friendlyId": "11111111111",
	"firstName": "John",
	"middleName": "Doe",
	"lastName": "Smith",
	"email": "jds@example.com",
	"customAttributes":
	{
		"active": false,
		"classes": 5,
		"company": "Acme",
		"memberSince": "1980-12-02T05:23:26-03:00"
	}
}

Exemplo de Resposta de Sucesso

{
	"created": false,
	"monitorUser":
	{ 
		"id": "d4JdixacSOUHzGuStMaUaOAjE8VF42WI"
	}
}

PATCH /lumis/api/rest/lumis/monitor/v1/monitor-users/{id}

Atualiza dados de um usuário monitorado.

Cabeçalhos de Requisição

Esta operação requer cabeçalhos na requisição compatíveis com:

Parâmetros na URI

Corpo da Requisição

O corpo da requisição deve ser um objeto JSON contendo as propriedades do usuário monitorado a serem alteradas. As propriedades aceitas neste objeto são as mesmas descritas no método POST acima, exceto friendlyId, que não é permitido ser declarado nesta operação.

Resposta de Sucesso

A resposta desta operação em caso de sucesso será o corpo vazio e código de resposta 204.

Resposta de Erro

Esta operação responde como erro o objeto JSON padrão de erro.

Exemplo de Requisição

Neste exemplo será atualizado o valor de email e será apagado o atributo customizado company, caso exista.

PATCH /lumis/api/rest/lumis/monitor/v1/monitor-users/d4JdixacSOUHzGuStMaUaOAjE8VF42WI HTTP/1.1
Content-Type: application/merge-patch+json
Accept: application/json
(... outros cabeçalhos ...)

{
	"email": "my_new_email@example.com",
	"customAttributes":
	{
		"company": null
	}
}

POST /lumis/api/rest/lumis/monitor/v1/monitor-users/{id}/identify

Identifica um usuário monitorado com um identificador amigável, retornando o identificador do usuário monitorado resultante com tal identificador amigável.

Se o usuário com o identificador dado não possui identificador amigável e não existe usuário com identificador amigável igual ao valor especificado, este usuário passará a ter o identificador amigável especificado e seu identificador será retornado.

Se o usuário com o identificador dado não possui identificador amigável mas já existe usuário com identificador amigável igual ao valor especificado, ambos usuários serão mesclados em um único usuário e o seu identificador será retornado.

Se o usuário com o identificador dado já possui identificador amigável igual ao valor especificado, nenhuma alteração será feita e o seu identificador será retornado.

Se o usuário com o identificador dado já possui identificador amigável mas diferente do valor especificado, e se não existir um usuário com este identificador amigável, um novo usuário monitorado será criado com o identificador amigável e o seu identificador será retornado.

Se o usuário com o identificador dado já possui identificador amigável diferente do valor especificado, e se existir um usuário com este identificador amigável, será retornado o identificador deste usuário já existente.

Cabeçalhos de Requisição

Esta operação requer cabeçalhos na requisição compatíveis com:

Parâmetros na URI

Corpo da Requisição

O corpo da requisição deve ser um objeto JSON com as propriedades listadas abaixo:

Resposta de Sucesso

Quando a operação é bem sucedida, a resposta conterá um objeto JSON com o identificador do usuário monitorado que possui o identificador amigável especificado.

Resposta de Erro

Esta operação responde como erro o objeto JSON padrão de erro.

Exemplo de Requisição

POST /lumis/api/rest/lumis/monitor/v1/monitor-users/d4JdixacSOUHzGuStMaUaOAjE8VF42WI/identify HTTP/1.1
Content-Type: application/json
Accept: application/json
(... outros cabeçalhos ...)

{
	"friendlyId": "111111111111"
}

Exemplo de Resposta de Sucesso

{
	"monitorUser":
	{
		"id": "d4JdixacSOUHzGuStMaUaOAjE8VF42WI"
	}
}