Integración con Power BI
Lleva los datos de Kana a Power BI o Excel y mantenlos al día con refrescos programados.
Qué datos ofrece Kana
Sección titulada «Qué datos ofrece Kana»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_cursorhasta que seanull. - Cada refresco trae las tablas completas, así los borrados desaparecen también del tablero.
- 60 llamadas por minuto por key.
Datos sensibles
Sección titulada «Datos sensibles»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 comoidentifier_hash. La antigua columna única<campo>ya no existe.
Para verlos en claro:
- Ten el permiso «Datos sensibles» (
sensitive_data:read) en el proyecto. Lo traen los roles operativos, no «Analista de datos». - 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.
Crear la clave de API
Sección titulada «Crear la clave de API»- En Kana, abre el menú de tu avatar → Claves de API → Nueva clave de API.
- Nombre: por ejemplo
Power BI · Tablero de inscripciones. - Alcance: Solo lectura (analítica).
- Proyectos: elige solo los que necesita el tablero.
- Vencimiento: 90 días o 1 año.
- 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.
Conectar desde Power BI Desktop
Sección titulada «Conectar desde Power BI Desktop»Parámetros
Sección titulada «Parámetros»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_… |
La función KanaTable
Sección titulada «La función KanaTable»Nuevo origen → Consulta en blanco → Editor avanzado. Pega esto y nombra la consulta KanaTable:
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 KanaTableLa 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 por tabla
Sección titulada «Una consulta por tabla»Una consulta en blanco por tabla:
= 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:
= Json.Document(Web.Contents(KanaUrl, [RelativePath = "analytics", Headers = [#"X-API-Key" = KanaApiKey]]))[data]Métricas
Sección titulada «Métricas»Un objeto con tres listas; crea tres consultas:
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.
Tipos y relaciones
Sección titulada «Tipos y relaciones»- 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 poridentifier_hash.
Publicar y programar el refresco
Sección titulada «Publicar y programar el refresco»- Publica el informe en el servicio de Power BI.
- 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.
- 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.
Errores frecuentes
Sección titulada «Errores frecuentes»| 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. |
Buenas prácticas
Sección titulada «Buenas prácticas»- 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.
Actualización incremental y frescura
Sección titulada «Actualización incremental y frescura»Para tableros grandes o sincronizaciones frecuentes: saber si algo cambió y traer solo lo nuevo.
Saber si algo cambió: analytics/freshness
Sección titulada «Saber si algo cambió: analytics/freshness»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.
Traer solo lo cambiado: updated_since
Sección titulada «Traer solo lo cambiado: updated_since»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:
recordsyenrollmentscomparan contraupdated_at.project-modulesno tiene fecha de modificación: compara contracreated_at, así que solo trae módulos nuevos.entitiesusa 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 desdeupdated_since(enrecords, del módulo pedido). Enentitiesllega vacío: la salida de un proyecto aparece enenrollments.sync_token: úsalo comoupdated_sinceen 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.
Caché HTTP: ETag y 304
Sección titulada «Caché HTTP: ETag y 304»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.
Actualización incremental en Power BI
Sección titulada «Actualización incremental en Power BI»Power BI recarga solo las particiones recientes de una tabla:
- En Transformar datos → Administrar parámetros, crea
RangeStartyRangeEnd(exactamente así), de tipo Fecha y hora. - Pasa
RangeStartcomoupdated_since(KanaTableya lo hace) y filtra porupdated_atdentro del rango:
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- 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.
- 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.