From bdf7f953c2dadef7e9594506965804c4f2454c70 Mon Sep 17 00:00:00 2001 From: Lucy Macartney Date: Mon, 12 Oct 2026 11:51:24 +0100 Subject: [PATCH 1/3] Update Spanish CLI Sync page and translate three unlisted pages cli-sync.md follows the English changes from #906. build-compliant-apps.md, build-with-api.md and design/overview.md are new translations. --- .../build-compliant-apps.md | 82 +++++++ .../build-for-developers/build-with-api.md | 13 ++ .../current/build-for-developers/cli-sync.md | 76 +++--- .../current/design/overview.md | 218 ++++++++++++++++++ 4 files changed, 359 insertions(+), 30 deletions(-) create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-with-api.md create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/design/overview.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md new file mode 100644 index 00000000000..46f82cc4622 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md @@ -0,0 +1,82 @@ +--- +title: Desarrollar aplicaciones conectadas +sidebar_label: Crear API compatibles +translation_source_hash: 02f208bd6abe5793e7707fe31fa6ac9e1780a494 +translation_review_status: machine +--- + +Esta sección es para ti si quieres crear una aplicación que se pueda conectar a +OpenFn, o ampliar una que ya tengas. Seguimos las pautas modernas de los +estándares web para las API JSON. + +Para que tu aplicación sea un proveedor de datos (o "origen") para las +integraciones de OpenFn, te recomendamos mucho que crees un "servicio de +notificaciones" (a veces llamado "servicio de webhooks" o "API push basada en +eventos"). Es mejor que usar una API REST por dos motivos: (1) un servicio de +notificaciones permite a tus clientes configurar integraciones en tiempo real, y +(2) un servicio de notificaciones es más eficiente tanto para tus servidores +como para OpenFn: en lugar de hacer y atender solicitudes cada X segundos, tus +servidores y los de OpenFn solo trabajan cuando hay datos nuevos. + +Para que tu aplicación sea un consumidor (o "destino") de OpenFn, debe tener una +API REST estándar basada en JSON, o tienes que crear un language-package que +cumpla las especificaciones de tu API. + +## Enviar datos a OpenFn {#sending-data-to-openfn} + +Para enviar datos a OpenFn, tu aplicación debe poder hacer un POST por HTTPS a +una URL externa, con un objeto JSON válido como cuerpo. Mira este ejemplo con +cURL: + +```sh +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Cache-Control: no-cache" \ + -d '{"foo":"bar", "baz":"qux"}' \ + "https://app.openfn.org/i/some-secret-inbox-uuid" +``` + +Si el POST se completa correctamente, OpenFn responde con un 200 y un objeto +JSON vacío. Un error 400 significa que la URL externa del usuario es incorrecta, +y un 500 significa que hay un error de la aplicación en OpenFn. Los errores 500 +son poco frecuentes, pero pueden deberse a un JSON no válido en el cuerpo del +POST. + +Si no puedes notificar a una URL externa cuando ocurre un evento, puedes +integrarte con OpenFn de todos modos si tienes una API REST basada en JSON. Los +usuarios de OpenFn pueden hacer solicitudes HTTP GET a tu aplicación y realizar +otras acciones según tu respuesta. Deberías permitir la autenticación básica o +por token, y responder con JSON a un GET válido. La respuesta no tiene que +seguir ningún formato concreto, porque los usuarios pueden procesarla como +quieran: extraer los datos que les interesan y luego hacer otras acciones con +ellos, como cargarlos en un sistema de destino. Consulta +[language-http](https://www.github.com/openfn/language-http) para ver cómo hacen +los usuarios estas solicitudes HTTP genéricas. + +### Tamaño del payload {#payload-sizing} + +Si usas la plataforma y no piensas contratar un plan empresarial, tendrás que +tener en cuenta el tamaño de los datos que envías en cada payload. El `state` de +un run suele estar limitado a `10MB`, así que deberías mantener tus payloads muy +por debajo de ese límite. + +## Recibir datos de OpenFn {#receiving-data-from-openfn} + +Para que los usuarios puedan conectarse fácilmente a tu aplicación, te +recomendamos mucho que crees un language-package con la autenticación que +necesitas y un conjunto de acciones sencillas y permitidas, bien abstraídas en +"funciones auxiliares". Consulta +[language-dhis2](https://www.github.com/openfn/language-dhis2) para ver un +ejemplo de language-package que crea una interfaz más sencilla para una API REST +tradicional basada en JSON. Los adaptors se escriben en JavaScript y se ejecutan +en Node. Puedes convertir el JSON de OpenFn a XML, o a cualquier otro formato, +antes de enviarlo a tu aplicación, y puedes usar los módulos de Node que +quieras. Consulta +[language-postgresql](https://www.github.com/openfn/language-postgresql) para +ver un ejemplo de adaptor que se conecta directamente a bases de datos +PostgreSQL con un módulo de NPM muy conocido llamado "pg". + +Para recibir datos del adaptor genérico `language-http` de OpenFn, tu aplicación +debe permitir solicitudes POST, PUT o GET con autenticación básica, por token o +digest. (Aunque no es recomendable crear una API que exija solicitudes GET para +crear o actualizar datos.) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-with-api.md b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-with-api.md new file mode 100644 index 00000000000..6cb3cdc67e1 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-with-api.md @@ -0,0 +1,13 @@ +--- +id: build-with-api +title: Crear proyectos con la API de OpenFn +sidebar_label: Crear con la API +slug: /build-with-api +translation_source_hash: 4578f2253ce460b1b667107c61855e2079036646 +translation_review_status: machine +--- + +OpenFn te permite configurar proyectos con solicitudes HTTP enviadas a la API +REST. Consulta el +[repositorio de OpenFn/Lightning en GitHub](https://openfn.github.io/lightning/provisioning.html) +para ver la documentación detallada para desarrolladores. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md index af2cc0b0e9e..3877f8419ac 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md @@ -2,7 +2,7 @@ title: OpenFn Sync sidebar_label: Sync slug: /sync -translation_source_hash: e4dbcbf31dd1975afc33be952424a6476b240f73 +translation_source_hash: 432be5126c87d7ddd1d025fe3787aedf638b2616 translation_review_status: machine --- @@ -71,55 +71,51 @@ siguiente estructura: ``` ├── openfn.yaml +├── resources.yaml ├── .projects │ ├── main@app.openfn.org.yaml └── workflows ├── my-workflow │ ├── my-workflow.yaml │ ├── my-step.js +├──.openfn ``` En resumen, estos archivos son: - `openfn.yaml` declara que esta carpeta es un proyecto de OpenFn y contiene - metadatos y ajustes + algunas opciones de configuración +- `resources.yaml` contiene los detalles de los recursos conectados, como + canales o colecciones. +- `workflows` contiene una subcarpeta por workflow y "expande" cada workflow en + el sistema de archivos para que sea más cómodo editarlo. - La carpeta `.projects` contiene una representación YAML completa de cada - proyecto -- La carpeta `workflows` muestra el contenido del proyecto: los steps, las - conexiones, etc. + proyecto. Las personas casi nunca la usan +- La carpeta `.openfn` contiene metadatos que usa la CLI. No está pensada para + las personas y no debería incluirse en git. -Veamos esta estructura con un poco más de detalle. - -### project.yaml {#projectyaml} - -El archivo de proyecto guarda una copia de todo el estado de un proyecto tal -como está guardado en la aplicación. Si lo abres, verás los workflows -representados como texto plano. - -El nombre de un archivo de proyecto tiene la forma `@.yaml`. El -alias es un nombre local que sirve para referirse a una versión concreta del -proyecto. El dominio es el de la instancia de OpenFn desde la que se descargó el -proyecto. +::: note -No deberías editar el archivo de proyecto localmente, porque cualquier cambio se -perderá la próxima vez que lo obtengas. +Si conoces bien la especificación de portabilidad de OpenFn, esta estructura de +carpetas representa la _spec_ de un proyecto. La carpeta `.projects` contiene el +_state_ del proyecto. -Puedes obtener tantos proyectos como quieras, y cada uno se guardará en su -propio archivo project.yaml. +::: -La carpeta `.projects` puede y debería incluirse en el control de versiones. +Veamos esta estructura con un poco más de detalle. ### workflows {#workflows} -Tener todo el proyecto dentro de un único archivo no es una buena forma de leer -o editar workflows. Por eso la CLI puede hacer "checkout" o "expandir" un -archivo de proyecto en el sistema de archivos. +Cada workflow se guarda como un conjunto de archivos, lo que facilita un poco +editar y fusionar esos workflows. -Hacer checkout es el proceso de escribir cada workflow en un archivo -workflow.yaml y cada step en un archivo step.js. Todo esto vive en el directorio -`workflows`. +Un workflow se puede definir en un solo archivo YAML. Lo verás si haces clic en +"View workflow as YAML" en la aplicación, o si miras los archivos de state del +proyecto en `.projects. Pero, por comodidad, también puedes hacer "checkout" del +workflow, o expandirlo, para que el código del job de cada step (su expresión) +se escriba en un archivo .js. -Aquí puedes editar los archivos todo lo que quieras, y los cambios se +Puedes editar estos archivos expandidos todo lo que quieras, y los cambios se registrarán cuando subas o despliegues de nuevo a la aplicación. Solo puedes hacer checkout de un proyecto a la vez. En realidad, esto viene muy @@ -164,7 +160,27 @@ archivo del step y la ruta de la clave `expression` en `workflow.yaml`. Es un archivo de configuración de nivel superior que, en general, puedes ignorar. Las herramientas de OpenFn lo usan para reconocer la carpeta raíz de un proyecto. También contiene opciones de configuración para todos los proyectos -locales y metadatos sobre el proyecto que tienes con checkout. +locales. + +### project.yaml {#projectyaml} + +El archivo de proyecto guarda una copia de todo el estado de un proyecto tal +como está guardado en la aplicación. Si lo abres, verás los workflows +representados como texto plano. + +El nombre de un archivo de proyecto tiene la forma `@.yaml`. El +alias es un nombre local que sirve para referirse a una versión concreta del +proyecto. El dominio es el de la instancia de OpenFn desde la que se descargó el +proyecto. + +No deberías editar el archivo de proyecto localmente, porque cualquier cambio se +perderá la próxima vez que lo obtengas. Representa estrictamente el estado del +servidor. + +Puedes obtener tantos proyectos como quieras, y cada uno se guardará en su +propio archivo project.yaml. + +La carpeta `.projects` puede y debería incluirse en el control de versiones. ## Autorización {#authorization} diff --git a/i18n/es/docusaurus-plugin-content-docs/current/design/overview.md b/i18n/es/docusaurus-plugin-content-docs/current/design/overview.md new file mode 100644 index 00000000000..7922964183d --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/design/overview.md @@ -0,0 +1,218 @@ +--- +sidebar_label: Proceso de diseño +title: Proceso de diseño de soluciones con OpenFn +translation_source_hash: 9bc0fa895989e88eb1ec2cb7cf607ac5d52888db +translation_review_status: machine +--- + +:::warning En construcción + +Esta página de la documentación está en construcción. Vuelve más adelante para +ver la documentación completa. + +::: + +# Primeros pasos con el diseño de automatización de workflows para proyectos de OpenFn + +Resumen del proceso de diseño y de sus principales resultados y artefactos... + +**El diseño de una integración empieza por los requisitos funcionales o de +negocio (no por los detalles técnicos).** Por eso, no necesitas ser consultor de +TI ni ingeniero de software para empezar a diseñar una solución de integración. +(Aunque contar con esos perfiles sin duda ayuda cuando llegamos a las +especificaciones técnicas... pero de eso hablaremos más adelante). + +Entender con claridad y _documentar_ los procesos de negocio, los requisitos +funcionales y las personas que interactúan con la integración que quieres es el +primer paso fundamental del diseño de una integración. Mientras planificas tu +próximo proyecto de integración, empieza a preparar la siguiente documentación +para poner en marcha la solución. + +## 1. Recoge los requisitos como historias de usuario {#1-capture-requirements-as-user-stories} + +Documentar _por qué_ se necesita la integración y cuáles son los requisitos que +la impulsan es importante para identificar las necesidades prioritarias y para +que todo el mundo tenga las mismas expectativas sobre el proyecto. + +Las _historias de usuario_ son descripciones breves y sencillas de un requisito, +contadas desde el punto de vista de la persona que quiere la nueva +funcionalidad. + +> Como ``, quiero `` para +> ``. + +Una buena historia de usuario recoge 3 partes: + +1. _Quién_: ¿quién usa la solución? +2. _Qué_: ¿qué espera conseguir con la solución? +3. _Por qué_: ¿por qué es importante este deseo? ¿Qué implicaciones tiene para + el negocio? + +Si recoges estos 3 elementos, las historias de usuario pueden ser una forma +eficaz de detallar los requisitos de una integración y de abrir conversaciones +en tu organización sobre qué requisitos son prioritarios. + +### Ejemplos de historias de usuario: {#example-user-stories} + +- **Derivación de casos:** como trabajador social, quiero enviar automáticamente + solicitudes de derivación a mi agencia asociada, que usa otro sistema de + gestión de casos, para compartir la información del caso de forma segura y + avisarles rápido cuando se necesiten sus servicios en una situación de crisis. +- **EMR - HIS:** como responsable de una clínica, me gustaría integrar los datos + de pacientes del sistema de historia clínica electrónica de la clínica del + distrito con el sistema nacional de información de salud DHIS2, para reportar + de forma segura y automática los resultados de salud de los indicadores clave + de mi distrito. +- **Kobo Toolbox - base de datos MSSQL:** como responsable de monitoreo y + evaluación, quiero supervisar en tiempo real las respuestas de las encuestas + de Kobo Toolbox en una base de datos central, para entender mejor las + actividades de recolección de datos y el desempeño del programa en los sitios + de mis socios de investigación. + +## 2. Haz un diagrama del proceso de negocio {#2-diagram-the-business-process} + +Una vez identificadas las historias de usuario, empieza a documentar los +procesos funcionales que ya existen (o que habrá que implementar) para cumplir +los requisitos. Pueden ser procesos automatizados o manuales, llevados a cabo +por personas. Este es el paso previo a trazar el flujo de datos (que detalla los +pasos técnicos de cómo se harán las conexiones y cómo se intercambiarán los +datos entre sistemas). De nuevo, trazar los procesos es _análisis de negocio_, +no un ejercicio técnico. + +Por ejemplo, si quieres intercambiar información entre tu organización y otra... +¿cómo funcionaría ese intercambio desde un punto de vista funcional? ¿_Qué_ +información se intercambiará? ¿Con _quién_ (entre qué sistemas o usuarios)? +¿_Cuándo_ se intercambiará la información? ¿Y qué pasos, humanos o +automatizados, deberían facilitar y desencadenar este intercambio? Estas +preguntas sobre el proceso de negocio se tratan con más detalle en la página +[So, what is an integration?](/documentation/tutorials/tutorial/). + +:::tip + +Recoge el proceso actual y el deseado Documenta los procesos de negocio +_actuales y deseados_ para determinar cómo debe intercambiarse la información +entre tu organización, sistema o usuarios y los demás, y para asegurarte de que +todos los socios comparten las mismas expectativas y supuestos. + +::: + +### Usa BPMN para documentar de forma estandarizada {#use-bpmn-for-standardized-documentation} + +Cuando documentes procedimientos de negocio internos, considera usar el estándar +Business Process Model and Notation (BPMN) para documentar gráficamente los +procesos de negocio clave. BPMN (más información sobre el estándar +[BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/)) usa símbolos parecidos a los de +un diagrama de flujo y una notación precisa que se puede traducir a componentes +de procesos de software. + +Estos recursos te ayudan a aprender y a crear tus propios diagramas BPMN: + +- `BPMN.io`, modelador de código abierto: https://bpmn.io/ +- `Camunda BPMN Tool` incluye una herramienta gratuita y un tutorial: + https://camunda.com/bpmn/ +- `LucidChart` ofrece una interfaz de diagramas muy fácil de usar: + https://www.lucidchart.com/pages/bpmn + +¿Buscas un curso rápido? Este video da un resumen rápido de BPMN y de cómo +usarlo: https://www.youtube.com/watch?v=BwkNceoybvA + +### Ejemplos de diagramas BPMN de OpenFn {#openfn-examples-of-bpmn-diagrams} + +Mira el siguiente ejemplo de diagrama BPMN para esta historia de usuario: + +> Como responsable de programa, quiero extraer los datos de los beneficiarios +> ("tracked entity instances") del sistema DHIS2 de mi país, para inscribirlos +> como contactos en mi campaña de SMS configurada en RapidPro y enviarles +> alertas automáticas y novedades del programa. + + + +## 3. Mapea los elementos de datos que se van a intercambiar {#3-map-data-elements-to-be-exchanged} + +Una vez documentados los procesos de negocio, empieza a documentar los elementos +de datos concretos que se van a intercambiar. Este ejercicio exige mucha +precisión para detallar cada uno de los "campos" o "atributos" que se +intercambiarán. + +El resultado de este ejercicio es una `Data Element Mapping Specification`, que +servirá (1) como documentación de los elementos de datos concretos que se acordó +intercambiar y (2) como guía para traducir el significado entre socios y +sistemas (por ejemplo, `client` en un sistema puede significar `patient` en +otro). + +Si tu organización ya tiene un acuerdo de gestión o de intercambio de datos, +puede ser el punto de partida perfecto para identificar los datos concretos que +se van a intercambiar. + +### Plantilla de especificación de mapeo {#mapping-specification-template} + +Colaborar con los socios implementadores en las especificaciones de mapeo es un +ejercicio importante para documentar requisitos muy concretos y llegar a un +consenso sobre qué datos exactamente se intercambiarán y cómo. + +:::tip Plantilla para empezar + +[Usa esta plantilla](https://docs.google.com/spreadsheets/d/1IqTIgOzyOztEevXbgY_4uE8Y8tiHXufZXx-IyJZase0/edit?usp=sharing) +para redactar tu propia especificación de mapeo de elementos de datos. + +::: + +Esta plantilla incluye: + +1. Detalles de los metadatos de origen, como el nombre del campo en la API, el + tipo de dato, valores de ejemplo y comentarios: + ![imagen](https://user-images.githubusercontent.com/80456839/130796010-fe900c03-1bff-40c0-9263-c29e22d9191f.png) +2. Detalles parecidos de los metadatos de destino: + ![imagen](https://user-images.githubusercontent.com/80456839/130796087-67b0359d-207a-4169-aa88-6609572b2561.png) +3. Notas sobre las transformaciones y la limpieza de datos necesarias, y + comentarios para hacer seguimiento de los cambios y de las preguntas para el + equipo técnico: + + ![imagen](https://user-images.githubusercontent.com/80456839/130796170-2e29a997-9b41-44f7-ac60-79375d096cc9.png) + +### Para crear una especificación de mapeo completa, tendrás que... {#to-build-a-complete-mapping-specification-youll-need-to} + +1. Definir los elementos de datos que intercambiarán los sistemas conectados (es + posible que tengas que exportar los metadatos del sistema de destino para + identificar los nombres exactos) +2. Determinar qué elementos de datos pertenecen al origen de datos y cuáles al + sistema de destino +3. Acordar cómo deben corresponderse los elementos de datos entre los sistemas +4. Analizar la estructura y la calidad de los datos para valorar si habrá que + transformar, limpiar o volver a etiquetar los valores para poder mapearlos + +Este mapeo servirá como plano para la configuración técnica de la integración, y +será un artefacto importante del acuerdo de intercambio de datos entre los +socios. + +### Consejos para redactar especificaciones de mapeo {#tips-for-drafting-mapping-specifications} + +- **Versiona los mapeos** para hacer seguimiento de las solicitudes de cambio a + lo largo del tiempo +- **Códigos de colores:** resalta con un color los campos que necesitan más + discusión y con otro los campos recién añadidos +- Usa Google Sheets o los comentarios de un documento compartido, y el correo + electrónico, para avisar a las personas adecuadas cuando haya cambios en los + mapeos +- Incluye una **leyenda o un README** que explique cómo usar la plantilla de + mapeo +- **Identificadores únicos:** dedica tiempo a evaluar los esquemas de + identificadores únicos disponibles y las opciones que ya puedan tener + implementadas los sistemas de información relacionados +- Cuando mapees preguntas de opción múltiple, ten en cuenta cómo deben + corresponderse las opciones de respuesta con el sistema de origen o de + destino. +- Consulta los consejos de mapeo para cada sistema en la sección `Apps` del + sitio de documentación (mira la barra lateral). + +## Próximos pasos {#next-steps} + +Cuando tengas definidas tus (1) `user stories`, (2) `business process diagrams` +y (3) `data element specifications`, habrás preparado un conjunto de +documentación de diseño funcional que guiará el diseño técnico de tu solución de +integración y dejará constancia de las decisiones de negocio y de los acuerdos +de los socios implementadores. + +Comparte esta documentación con el equipo técnico de implementación, o consulta +la sección de documentación [Build](/documentation/build/workflows) para ver +cómo implementar estas especificaciones de diseño con OpenFn. From 317c742c412d643babdf5e1ce0a78fa485e44fb6 Mon Sep 17 00:00:00 2001 From: Lucy Macartney Date: Mon, 12 Oct 2026 12:09:00 +0100 Subject: [PATCH 2/3] small fixes to english pages - typos and broken links --- .../build-compliant-apps.md | 35 +++++++++---------- docs/build-for-developers/cli-sync.md | 12 +++---- docs/design/overview.md | 33 ++++++++--------- .../build-compliant-apps.md | 16 ++++----- .../current/build-for-developers/cli-sync.md | 14 ++++---- .../current/design/overview.md | 24 ++++++------- 6 files changed, 63 insertions(+), 71 deletions(-) diff --git a/docs/build-for-developers/build-compliant-apps.md b/docs/build-for-developers/build-compliant-apps.md index 02f208bd6ab..e0d8e1d398d 100644 --- a/docs/build-for-developers/build-compliant-apps.md +++ b/docs/build-for-developers/build-compliant-apps.md @@ -7,10 +7,10 @@ This section is for you if you are hoping to build or extend an existing application that can connect to OpenFn. We follow modern web-standard JSON API guidelines. -For your application to a be data provider (or "source") for OpenFn +For your application to be a data provider (or "source") for OpenFn integrations, we highly recommend that you create a "notifications service" (sometimes called a "webhooks service" or "event-based push API"). This is -preferable to using a REST api for two reasons: (1) A notifications service will +preferable to using a REST API for two reasons: (1) A notifications service will give your clients the ability to set up real-time integrations, and (2) a notifications service is more efficient for both your servers and OpenFn—instead of having requests be made and handled every X seconds, your servers and @@ -35,19 +35,19 @@ curl -X POST \ ``` OpenFn will respond with a 200 and an empty JSON object in the event of a -successful post. 400s mean that the user's external URL is wrong, and 500s means +successful post. 400s mean that the user's external URL is wrong, and 500s mean that there is an application error on OpenFn. While 500s are rare, they could be due to invalid JSON in your POST body. If you cannot notify an external URL when some event takes place, you can still integrate with OpenFn if you have a JSON-based REST API. OpenFn users can make HTTP GET requests to your application and perform additional actions based on -your response. You should allow either basic or token authentication and -response to a valid GET with JSON. There is no specific format for your -response, as users can parse it any way they'd like, extracting relevant data -and then performing other actions—like loading it into a destination system—with -that data. See [language-http](https://www.github.com/openfn/language-http) for -details on how users make these generic HTTP requests. +your response. You should allow either basic or token authentication and respond +to a valid GET with JSON. There is no specific format for your response, as +users can parse it any way they'd like, extracting relevant data and then +performing other actions—like loading it into a destination system—with that +data. See [language-http](/adaptors/http) for details on how users make these +generic HTTP requests. ### Payload sizing @@ -61,15 +61,14 @@ keep your payloads well below that limit. To make it easy for users to connect to your application, it's highly recommended that you create a language-package with your required authentication and a set of simple, allowable actions nicely abstracted into "helper -functions". See [language-dhis2](https://www.github.com/openfn/language-dhis2) -for an example of a language-package which creates a simpler interface for a -traditional JSON-based REST api. Adaptors are written in Javascript and execute -in Node. You can convert OpenFn's JSON into XML, or any other format before -sending it to your application and you may make use of any node modules you'd -like. See -[language-postgresql](https://www.github.com/openfn/language-postgresql) for an -example of an adaptor that connects directly to PostgreSQL databases using a -popular NPM module called "pg". +functions". See [language-dhis2](/adaptors/dhis2) for an example of a +language-package which creates a simpler interface for a traditional JSON-based +REST API. Adaptors are written in JavaScript and execute in Node. You can +convert OpenFn's JSON into XML, or any other format before sending it to your +application and you may make use of any node modules you'd like. See +[language-postgresql](/adaptors/postgresql) for an example of an adaptor that +connects directly to PostgreSQL databases using a popular NPM module called +"pg". To receive data from OpenFn's generic `language-http` adaptor, your application must allow either basic, token, or digest authenticated POST, PUT, or GET diff --git a/docs/build-for-developers/cli-sync.md b/docs/build-for-developers/cli-sync.md index 432be5126c8..00115e52a11 100644 --- a/docs/build-for-developers/cli-sync.md +++ b/docs/build-for-developers/cli-sync.md @@ -69,7 +69,7 @@ Whether using the CLI or GitHub Sync, a Project has the following structure: ├── my-workflow │ ├── my-workflow.yaml │ ├── my-step.js -├──.openfn +├── .openfn ``` Briefly, these files are: @@ -81,11 +81,11 @@ Briefly, these files are: - `workflows` contains one sub folder per workflow, and "expands" a workflow to the file system for convenient editing. - The `.projects` folder contains a complete YAML representation of each - Project. This is rarely used by humans + Project. This is rarely used by humans. - The `.openfn` folder contains metadata used by the CLI. It is not used by humans and should not be checked-in to git. -::: note +:::note For users well-versed in the OpenFn portability specification, this folder structure represents a project _spec_. The `.projects` folder contains project @@ -102,12 +102,12 @@ workflows a little easier. A workflow can be defined as a single yaml file - you'll see that if you hit "View workflow as YAML" in the app, or if you look at the project state files in -`.projects. But for convenience, the workflow can also be "checked out" or +`.projects`. But for convenience, the workflow can also be "checked out" or expanded so that each step has its job code (its expression) written to a .js file. -You edit these expanded workflow files as much as you like, and changes will be -tracked when you push/deploy back to the app. +You can edit these expanded workflow files as much as you like, and changes will +be tracked when you push/deploy back to the app. You can only check out one project at a time. This is actually great for working with git, because you can checkout two projects on different branches and diff --git a/docs/design/overview.md b/docs/design/overview.md index 9bc0fa89598..7e56c3a8e3e 100644 --- a/docs/design/overview.md +++ b/docs/design/overview.md @@ -43,7 +43,7 @@ Good user stories will capture 3 parts: 2. _What_ - what do they hope to achieve via the solution? 3. _Why_ - why is this desire important? What are the business implications? -If you capture these 3 elements, user stories can b ean effective way of +If you capture these 3 elements, user stories can be an effective way of detailing integration requirements and starting discussions at your organization about which requirements are priority. @@ -57,8 +57,8 @@ about which requirements are priority. from the district clinic electronic medical record system with the national DHIS2 health information system, so that I can securely and automatically report on health outcomes for key indicators in my district. -- **Kobo Toolbox - MSSQL Database:** As a M&E manager, I want to monitor Kobo - Toolbox survey responses in a central database in real-time, so that I can +- **KoboToolbox - MSSQL Database:** As a M&E manager, I want to monitor + KoboToolbox survey responses in a central database in real-time, so that I can better understand data collection activities and program performance across my research partner sites. @@ -66,7 +66,7 @@ about which requirements are priority. Once the user stories have been identified, start to document the functional processes that are in place (or will need to be implemented) in order to achieve -the desired requirments. These might be automated or human/manually-driven +the desired requirements. These might be automated or human/manually-driven processes. This is the precursor step to mapping out the data flow (which details the technical steps for how connections will be made and data exchanged between systems). Again, process mapping is _business analysis_–not a technical @@ -76,16 +76,13 @@ For example, if you want to exchange information between your organization and another... how might this exchange work from a functional point of view? _What_ information will be exchanged? With _whom_ (between which systems or users)? _When_ will the information be exchanged? And what are the human or automation -steps that should facilitate and trigger this exchange? These business process -questions are discussed in more detail on the -[So, what is an integration?](/documentation/tutorials/tutorial/) page. +steps that should facilitate and trigger this exchange? -:::tip +:::tip Capture the current & desired process -Capture the current & desired process Document _current and desired_ business -processes in order to determine how information should be exchanged between your -organization/system/users and others, and to ensure alignment of expectations -and assumptions across partners. +Document _current and desired_ business processes in order to determine how +information should be exchanged between your organization/system/users and +others, and to ensure alignment of expectations and assumptions across partners. ::: @@ -125,10 +122,10 @@ Once the business processes are documented, start to document the specific data elements to be exchanged. This exercise requires a lot of specificity to detail the individual "fields" or "attributes" to be exchanged. -The output of this exerice is a `Data Element Mapping Specification`, which will -serve as (1) documentation of the specific data elements agreed to be exchanges, -as well as (2) a guide for how to translate meaning between partners and systems -(e.g., `client` in one system might mean `patient` in another). +The output of this exercise is a `Data Element Mapping Specification`, which +will serve as (1) documentation of the specific data elements agreed to be +exchanged, as well as (2) a guide for how to translate meaning between partners +and systems (e.g., `client` in one system might mean `patient` in another). If your organization already has a data management or sharing agreement, this might be the perfect starting point for identifying the specific data points to @@ -197,5 +194,5 @@ solution, as well as memorialize the business decisions and agreements made by implementing partners. Share this documentation with any technical implementation team, or check out -the [Build](/documentation/build/workflows) documentation section to learn how -to implement these design specifications using OpenFn. +the [Build](/build/workflows.md) documentation section to learn how to implement +these design specifications using OpenFn. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md index 46f82cc4622..ee5f97b2af4 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md @@ -1,7 +1,7 @@ --- title: Desarrollar aplicaciones conectadas sidebar_label: Crear API compatibles -translation_source_hash: 02f208bd6abe5793e7707fe31fa6ac9e1780a494 +translation_source_hash: e0d8e1d398d235e8cb533a3eb6d4f55280ad62d5 translation_review_status: machine --- @@ -50,8 +50,8 @@ por token, y responder con JSON a un GET válido. La respuesta no tiene que seguir ningún formato concreto, porque los usuarios pueden procesarla como quieran: extraer los datos que les interesan y luego hacer otras acciones con ellos, como cargarlos en un sistema de destino. Consulta -[language-http](https://www.github.com/openfn/language-http) para ver cómo hacen -los usuarios estas solicitudes HTTP genéricas. +[language-http](/adaptors/http) para ver cómo hacen los usuarios estas +solicitudes HTTP genéricas. ### Tamaño del payload {#payload-sizing} @@ -65,16 +65,14 @@ por debajo de ese límite. Para que los usuarios puedan conectarse fácilmente a tu aplicación, te recomendamos mucho que crees un language-package con la autenticación que necesitas y un conjunto de acciones sencillas y permitidas, bien abstraídas en -"funciones auxiliares". Consulta -[language-dhis2](https://www.github.com/openfn/language-dhis2) para ver un +"funciones auxiliares". Consulta [language-dhis2](/adaptors/dhis2) para ver un ejemplo de language-package que crea una interfaz más sencilla para una API REST tradicional basada en JSON. Los adaptors se escriben en JavaScript y se ejecutan en Node. Puedes convertir el JSON de OpenFn a XML, o a cualquier otro formato, antes de enviarlo a tu aplicación, y puedes usar los módulos de Node que -quieras. Consulta -[language-postgresql](https://www.github.com/openfn/language-postgresql) para -ver un ejemplo de adaptor que se conecta directamente a bases de datos -PostgreSQL con un módulo de NPM muy conocido llamado "pg". +quieras. Consulta [language-postgresql](/adaptors/postgresql) para ver un +ejemplo de adaptor que se conecta directamente a bases de datos PostgreSQL con +un módulo de NPM muy conocido llamado "pg". Para recibir datos del adaptor genérico `language-http` de OpenFn, tu aplicación debe permitir solicitudes POST, PUT o GET con autenticación básica, por token o diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md index 3877f8419ac..e6936d10e2c 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md @@ -2,7 +2,7 @@ title: OpenFn Sync sidebar_label: Sync slug: /sync -translation_source_hash: 432be5126c87d7ddd1d025fe3787aedf638b2616 +translation_source_hash: 00115e52a11ca812e0959d7b74220077ac5e72fd translation_review_status: machine --- @@ -78,7 +78,7 @@ siguiente estructura: ├── my-workflow │ ├── my-workflow.yaml │ ├── my-step.js -├──.openfn +├── .openfn ``` En resumen, estos archivos son: @@ -90,11 +90,11 @@ En resumen, estos archivos son: - `workflows` contiene una subcarpeta por workflow y "expande" cada workflow en el sistema de archivos para que sea más cómodo editarlo. - La carpeta `.projects` contiene una representación YAML completa de cada - proyecto. Las personas casi nunca la usan + proyecto. Las personas casi nunca la usan. - La carpeta `.openfn` contiene metadatos que usa la CLI. No está pensada para las personas y no debería incluirse en git. -::: note +:::note Si conoces bien la especificación de portabilidad de OpenFn, esta estructura de carpetas representa la _spec_ de un proyecto. La carpeta `.projects` contiene el @@ -111,9 +111,9 @@ editar y fusionar esos workflows. Un workflow se puede definir en un solo archivo YAML. Lo verás si haces clic en "View workflow as YAML" en la aplicación, o si miras los archivos de state del -proyecto en `.projects. Pero, por comodidad, también puedes hacer "checkout" del -workflow, o expandirlo, para que el código del job de cada step (su expresión) -se escriba en un archivo .js. +proyecto en `.projects`. Pero, por comodidad, también puedes hacer "checkout" +del workflow, o expandirlo, para que el código del job de cada step (su +expresión) se escriba en un archivo .js. Puedes editar estos archivos expandidos todo lo que quieras, y los cambios se registrarán cuando subas o despliegues de nuevo a la aplicación. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/design/overview.md b/i18n/es/docusaurus-plugin-content-docs/current/design/overview.md index 7922964183d..04386024fcb 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/design/overview.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/design/overview.md @@ -1,7 +1,7 @@ --- sidebar_label: Proceso de diseño title: Proceso de diseño de soluciones con OpenFn -translation_source_hash: 9bc0fa895989e88eb1ec2cb7cf607ac5d52888db +translation_source_hash: 7e56c3a8e3ef74888478af0628a31d8c54759d88 translation_review_status: machine --- @@ -63,9 +63,9 @@ en tu organización sobre qué requisitos son prioritarios. distrito con el sistema nacional de información de salud DHIS2, para reportar de forma segura y automática los resultados de salud de los indicadores clave de mi distrito. -- **Kobo Toolbox - base de datos MSSQL:** como responsable de monitoreo y +- **KoboToolbox - base de datos MSSQL:** como responsable de monitoreo y evaluación, quiero supervisar en tiempo real las respuestas de las encuestas - de Kobo Toolbox en una base de datos central, para entender mejor las + de KoboToolbox en una base de datos central, para entender mejor las actividades de recolección de datos y el desempeño del programa en los sitios de mis socios de investigación. @@ -83,16 +83,14 @@ Por ejemplo, si quieres intercambiar información entre tu organización y otra. ¿cómo funcionaría ese intercambio desde un punto de vista funcional? ¿_Qué_ información se intercambiará? ¿Con _quién_ (entre qué sistemas o usuarios)? ¿_Cuándo_ se intercambiará la información? ¿Y qué pasos, humanos o -automatizados, deberían facilitar y desencadenar este intercambio? Estas -preguntas sobre el proceso de negocio se tratan con más detalle en la página -[So, what is an integration?](/documentation/tutorials/tutorial/). +automatizados, deberían facilitar y desencadenar este intercambio? -:::tip +:::tip Recoge el proceso actual y el deseado -Recoge el proceso actual y el deseado Documenta los procesos de negocio -_actuales y deseados_ para determinar cómo debe intercambiarse la información -entre tu organización, sistema o usuarios y los demás, y para asegurarte de que -todos los socios comparten las mismas expectativas y supuestos. +Documenta los procesos de negocio _actuales y deseados_ para determinar cómo +debe intercambiarse la información entre tu organización, sistema o usuarios y +los demás, y para asegurarte de que todos los socios comparten las mismas +expectativas y supuestos. ::: @@ -214,5 +212,5 @@ integración y dejará constancia de las decisiones de negocio y de los acuerdos de los socios implementadores. Comparte esta documentación con el equipo técnico de implementación, o consulta -la sección de documentación [Build](/documentation/build/workflows) para ver -cómo implementar estas especificaciones de diseño con OpenFn. +la sección de documentación [Build](/build/workflows.md) para ver cómo +implementar estas especificaciones de diseño con OpenFn. From 17318451902426a31d74806cf607e2a39d581998 Mon Sep 17 00:00:00 2001 From: Lucy Macartney Date: Mon, 12 Oct 2026 13:10:41 +0100 Subject: [PATCH 3/3] review translation fixes --- .../current/build-for-developers/build-compliant-apps.md | 6 +++--- .../current/build-for-developers/cli-sync.md | 8 ++++---- .../current/design/overview.md | 9 +++++---- 3 files changed, 12 insertions(+), 11 deletions(-) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md index ee5f97b2af4..2e584f1de36 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/build-compliant-apps.md @@ -18,9 +18,9 @@ notificaciones permite a tus clientes configurar integraciones en tiempo real, y como para OpenFn: en lugar de hacer y atender solicitudes cada X segundos, tus servidores y los de OpenFn solo trabajan cuando hay datos nuevos. -Para que tu aplicación sea un consumidor (o "destino") de OpenFn, debe tener una -API REST estándar basada en JSON, o tienes que crear un language-package que -cumpla las especificaciones de tu API. +Para que tu aplicación sea un consumidor (o "destino") de OpenFn, debes tener +una API REST estándar basada en JSON o crear un language-package que cumpla las +especificaciones de tu API. ## Enviar datos a OpenFn {#sending-data-to-openfn} diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md index e6936d10e2c..36f716e277d 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/build-for-developers/cli-sync.md @@ -360,10 +360,10 @@ De forma predeterminada, `openfn project deploy` toma el proyecto con checkout y lo sube al servidor del que vino originalmente (según lo define el archivo de proyecto). -Pero también puedes usar deploy para sincronizar entre proyectos. Normalmente lo -harás para promover un sandbox de desarrollo o de staging a producción. Incluso -puedes usarlo para desplegar un proyecto de la aplicación SaaS en otra instancia -de OpenFn completamente distinta. +Pero también puedes usar deploy para sincronizar entre proyectos. Normalmente +querrás hacerlo para promover un sandbox de desarrollo o de staging a +producción. Incluso puedes usarlo para desplegar un proyecto de la aplicación +SaaS en otra instancia de OpenFn completamente distinta. ### Desplegar directamente desde un archivo de spec o de state {#deploy-straight-from-a-spec-or-state-file} diff --git a/i18n/es/docusaurus-plugin-content-docs/current/design/overview.md b/i18n/es/docusaurus-plugin-content-docs/current/design/overview.md index 04386024fcb..885278726a7 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/design/overview.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/design/overview.md @@ -88,8 +88,8 @@ automatizados, deberían facilitar y desencadenar este intercambio? :::tip Recoge el proceso actual y el deseado Documenta los procesos de negocio _actuales y deseados_ para determinar cómo -debe intercambiarse la información entre tu organización, sistema o usuarios y -los demás, y para asegurarte de que todos los socios comparten las mismas +debería intercambiarse la información entre tu organización, sistema o usuarios +y los demás, y para asegurarte de que todos los socios comparten las mismas expectativas y supuestos. ::: @@ -175,7 +175,8 @@ Esta plantilla incluye: identificar los nombres exactos) 2. Determinar qué elementos de datos pertenecen al origen de datos y cuáles al sistema de destino -3. Acordar cómo deben corresponderse los elementos de datos entre los sistemas +3. Acordar cómo deberían corresponderse los elementos de datos entre los + sistemas 4. Analizar la estructura y la calidad de los datos para valorar si habrá que transformar, limpiar o volver a etiquetar los valores para poder mapearlos @@ -197,7 +198,7 @@ socios. - **Identificadores únicos:** dedica tiempo a evaluar los esquemas de identificadores únicos disponibles y las opciones que ya puedan tener implementadas los sistemas de información relacionados -- Cuando mapees preguntas de opción múltiple, ten en cuenta cómo deben +- Cuando mapees preguntas de opción múltiple, ten en cuenta cómo deberían corresponderse las opciones de respuesta con el sistema de origen o de destino. - Consulta los consejos de mapeo para cada sistema en la sección `Apps` del