Ir al contenido

Integración con Power BI

Lleva los datos de Kana a Power BI o Excel y mantenlos al día con refrescos programados.

Un feed de analítica de solo lectura en https://<tu-kana>/api/public/v1/analytics/…. Tablas planas, columnas en snake_case, fechas ISO 8601 (UTC), ids como texto. Excel usa el mismo Power Query.

Tabla Ruta Qué contiene
Catálogo analytics Proyectos, módulos con columnas y vistas. Úsalo para encontrar ids.
Proyectos analytics/projects Un proyecto por fila.
Módulos de proyecto analytics/project-modules Cada módulo dentro de cada proyecto (project_module_id).
Entidades analytics/entities Personas, empresas, vacantes… inscritas en tus proyectos.
Inscripciones analytics/enrollments Entidad × proyecto, con su estado y módulo actual.
Registros de un módulo analytics/records?project_module_id=<id> Una fila por registro, una columna tipada por campo.
Vista consolidada analytics/views/<viewId>/rows Las filas de una vista armada en el workspace.
Métricas analytics/metrics KPIs, tendencias de 6 meses y distribuciones del panel.
{ "data": [ { "project_id": "…", "name": "…" } ], "meta": { "next_cursor": "eyJj…", "limit": 1000 } }
  • Páginas de hasta 1.000 filas; sigue con cursor = meta.next_cursor hasta que sea null.
  • Cada refresco trae las tablas completas, así los borrados desaparecen también del tablero.
  • 60 llamadas por minuto por key.

Por defecto el feed no entrega datos sensibles:

  • Los campos marcados como «Dato sensible» (documento, teléfono, salud, etnia…) no aparecen como columnas.
  • Las entidades no traen sus properties.
  • El identificador llega como identifier_hash: estable por persona, sirve para cruzar tablas y no se puede revertir.
  • Un campo Documento llega en dos columnas: <campo>_tipo (CC, TI, PA…, en claro) y <campo>_numero, seudonimizado como identifier_hash. La antigua columna única <campo> ya no existe.

Para verlos en claro:

  1. Ten el permiso «Datos sensibles» (sensitive_data:read) en el proyecto. Lo traen los roles operativos, no «Analista de datos».
  2. Crea la clave con «Incluir datos sensibles».

Cada página con datos sensibles queda en la auditoría. Según la Ley 1581 de 2012, úsalos solo para la finalidad autorizada.

  1. En Kana, abre el menú de tu avatar → Claves de API → Nueva clave de API.
  2. Nombre: por ejemplo Power BI · Tablero de inscripciones.
  3. Alcance: Solo lectura (analítica).
  4. Proyectos: elige solo los que necesita el tablero.
  5. Vencimiento: 90 días o 1 año.
  6. Copia la key (kn_…). Solo se muestra una vez.

Con el centro de Analítica en el menú lateral, el asistente crea la key y te entrega la consulta lista.

En Power BI Desktop: Transformar datos → Administrar parámetros → Nuevo.

Nombre Tipo Valor
KanaUrl Texto https://<tu-kana>/api/public/v1/ (con la barra final)
KanaApiKey Texto Tu key kn_…

Nuevo origen → Consulta en blanco → Editor avanzado. Pega esto y nombra la consulta KanaTable:

Power Query (M)
let
KanaPage = (path as text, query as record) as record =>
Json.Document(
Web.Contents(
KanaUrl,
[
RelativePath = path,
Query = query,
Headers = [#"X-API-Key" = KanaApiKey, Accept = "application/json"]
]
)
),
KanaTable = (path as text, optional query as nullable record) as table =>
let
baseQuery = Record.Combine({[limit = "1000"], if query = null then [] else query}),
pages = List.Generate(
() => KanaPage(path, baseQuery),
(page) => page <> null,
(page) =>
let
nextCursor = page[meta][next_cursor]
in
if nextCursor = null
then null
else KanaPage(path, Record.Combine({baseQuery, [cursor = nextCursor]}))
),
rows = List.Combine(List.Transform(pages, each _[data]))
in
if List.IsEmpty(rows)
then #table({}, {})
else Table.FromRecords(rows, null, MissingField.UseNull)
in
KanaTable

La URL base es fija y la ruta va en RelativePath: si la URL se concatena, el servicio de Power BI no puede refrescar.

Una consulta en blanco por tabla:

Power Query (M)
= KanaTable("analytics/projects")
= KanaTable("analytics/project-modules")
= KanaTable("analytics/entities")
= KanaTable("analytics/enrollments")
= KanaTable("analytics/records", [project_module_id = "PEGA_AQUI_EL_ID_DEL_MODULO"])
= KanaTable("analytics/views/PEGA_AQUI_EL_ID_DE_LA_VISTA/rows")

Los ids de módulos y vistas están en el catálogo:

Power Query (M)
= Json.Document(Web.Contents(KanaUrl, [RelativePath = "analytics", Headers = [#"X-API-Key" = KanaApiKey]]))[data]

Un objeto con tres listas; crea tres consultas:

Power Query (M)
let
Metrics = Json.Document(
Web.Contents(KanaUrl, [RelativePath = "analytics/metrics", Headers = [#"X-API-Key" = KanaApiKey]])
)[data]
in
Table.FromRecords(Metrics[kpis])

Cambia kpis por trends o distributions en las otras dos. Para un solo proyecto, agrega Query = [project_id = "…"] a Web.Contents.

  • Revisa el tipo de cada columna en el editor.
  • Relaciona las tablas por sus ids: records.enrollment_id → enrollments.enrollment_id, records.project_module_id → project-modules.project_module_id, enrollments.entity_id → entities.entity_id, enrollments.project_id → projects.project_id. Sin datos sensibles, también puedes cruzar por identifier_hash.
  1. Publica el informe en el servicio de Power BI.
  2. En el modelo semántico: Configuración → Credenciales del origen de datos → Editar credenciales de la URL de Kana. Método: Anónimo (la key viaja en la cabecera). Nivel de privacidad: Organizativo. Marca Omitir prueba de conexión si el servicio lo pide.
  3. Actualización programada: hasta 8 por día con Pro, 48 con Premium por usuario o Fabric.

Para refrescar en cuanto cambian los datos, crea una conexión de refresco desde el centro de Analítica (requiere un administrador de Microsoft 365) o usa un flujo de Power Automate propio.

Código Qué significa Qué hacer
401 Key inválida, revocada, vencida o de un usuario inactivo. Crea otra y actualiza KanaApiKey.
403 Falta el alcance. Usa «Solo lectura (analítica)».
404 Fuera de los proyectos de la key o de tus permisos. Revisa la key y tus permisos.
429 Más de 60 llamadas por minuto. Espera Retry-After segundos.
503 Feed sin configurar en el servidor. Avisa al administrador de Kana.
  • La key queda dentro del .pbix: comparte el informe publicado, no el archivo.
  • Una key por tablero, de solo lectura y con vencimiento. Consulta Autenticación.

Para tableros grandes o sincronizaciones frecuentes: saber si algo cambió y traer solo lo nuevo.

Una fila por proyecto de la key, con su versión de datos y su último cambio:

{ "data": [ { "project_id": "…", "data_version": 42, "last_change_at": "2026-10-03T14:05:12.345Z" } ] }

La versión sube con cualquier alta, cambio o borrado del proyecto, sus módulos, inscripciones, entidades o registros, venga de donde venga. Sin versión aún: data_version 0 y last_change_at nulo. Si ninguna versión cambió desde tu última lectura, no hace falta leer nada más.

records, enrollments, project-modules y entities aceptan updated_since (ISO 8601 con zona, p. ej. 2026-10-01T00:00:00Z) y devuelven solo lo creado o modificado después:

  • records y enrollments comparan contra updated_at.
  • project-modules no tiene fecha de modificación: compara contra created_at, así que solo trae módulos nuevos.
  • entities usa su creación o el último cambio de sus inscripciones. Editar solo sus propiedades no se detecta: requiere un refresco completo.

La primera página trae además en meta:

{
"data": [ … ],
"meta": {
"next_cursor": "eyJj…",
"limit": 1000,
"deleted_ids": ["…", "…"],
"sync_token": "2026-10-03T14:10:00.000Z"
}
}
  • deleted_ids: filas borradas desde updated_since (en records, del módulo pedido). En entities llega vacío: la salida de un proyecto aparece en enrollments.
  • sync_token: úsalo como updated_since en la siguiente sincronización.

Las páginas siguientes usan cursor con el mismo updated_since; mezclar cursores de consultas incrementales y completas da 400.

Los borrados se conservan 90 días. Un updated_since más antiguo da 409 SYNC_TOKEN_EXPIRED: recarga la tabla completa y sigue con su sync_token.

Todas las respuestas del feed traen ETag. Repite la consulta con If-None-Match: <ETag anterior>: si nada cambió, Kana responde 304 Not Modified sin cuerpo (ni registro de auditoría). Power BI no lo envía; sirve para scripts e integraciones propias.

Power BI recarga solo las particiones recientes de una tabla:

  1. En Transformar datos → Administrar parámetros, crea RangeStart y RangeEnd (exactamente así), de tipo Fecha y hora.
  2. Pasa RangeStart como updated_since (KanaTable ya lo hace) y filtra por updated_at dentro del rango:
Power Query (M)
let
// Kana conserva los borrados 90 días; las particiones más viejas se cargan completas.
Limite = DateTimeZone.RemoveZone(DateTimeZone.FixedUtcNow()) - #duration(80, 0, 0, 0),
// Un segundo de margen: updated_since es estricto (>) y el filtro de Power BI es >=.
Desde = DateTime.ToText(
RangeStart - #duration(0, 0, 0, 1),
[Format = "yyyy-MM-dd'T'HH:mm:ss'Z'", Culture = "en-US"]
),
Parametros = [project_module_id = "PEGA_AQUI_EL_ID_DEL_MODULO"],
Consulta = if RangeStart >= Limite
then Record.Combine({Parametros, [updated_since = Desde]})
else Parametros,
Fuente = KanaTable("analytics/records", Consulta),
ConFecha = Table.TransformColumns(
Fuente,
{{"updated_at", each DateTimeZone.RemoveZone(DateTimeZone.FromText(_)), type datetime}}
),
EnRango = Table.SelectRows(ConFecha, each [updated_at] >= RangeStart and [updated_at] < RangeEnd)
in
EnRango
  1. En la vista de modelo, clic derecho sobre la tabla → Actualización incremental (por ejemplo, archivar 2 años, actualizar 7 días). El aviso de plegado de consultas es normal con un origen web.
  2. Publica. El primer refresco carga todo el histórico.

Fechas y rangos se interpretan en UTC. Dos límites:

  • Borrados y registros viejos editados quedan en particiones archivadas: programa un refresco completo periódico (por ejemplo, semanal).
  • Solo vale en tablas grandes, como records; refresca completas las demás.