En Maximo Application Suite, los documentos e imágenes se almacenan como adjuntos y se vinculan a través de DOCLINKS. Aunque esto es sencillo en la interfaz de usuario, recuperar estos adjuntos programáticamente es menos obvio.
‍

Esta publicación detalla un patrón sencillo para usar la API REST para:
‍

1. Localizar un documento a través de DOCLINKS

2. Recuperar el contenido binario real, incluidas las imágenes

Comprendiendo el flujo

Maximo no almacena los binarios de los documentos directamente en los objetos de negocio principales. En su lugar:

• El objeto DOCLINKS almacena metadatos sobre los adjuntos que vinculan archivos y registros

• El DOCINFO representa el contenido real del archivo y se recupera a través de un punto final de documento
  ‍
  ‍

Debido a esto, el proceso siempre implica dos pasos:

1. Consultar DOCLINKS para identificar el archivo adjunto

2. Utilice el identificador devuelto para obtener el contenido

Mi escenario

En Maximo, he añadido mi foto de perfil como archivo adjunto a mis registros de persona. Mi registro de persona es PHIL.RUNION para este ejemplo. Como parte de este ejemplo, voy a utilizar la estructura de objeto MXPERSON para extraer mi foto de perfil de mi registro de persona utilizando la API REST y Postman.

Requisitos previos

• Tener acceso a la estructura de objetos en Manage

• Tener una clave API de Manage para su usuario

Paso 1: Configurar una estructura de objeto

Comenzaré con la estructura de objeto MXPERSON, duplicándola y añadiendo el objeto DOCLINKS como objeto de origen. Puede utilizar estructuras de objeto predefinidas si ya tienen el objeto de origen DOCLINKS.  

• Duplicar la estructura de objeto MXPERSON en Manage

• Añadir DOCLINKS como objeto de origen con relación al objeto principal

• Configurar el acceso de seguridad para la estructura de objeto

Paso 2: Usar Postman para extraer su registro

A continuación, estableceré una consulta REST básica en Postman para extraer mi registro de persona. Esto no solo establece una conexión sobre la que podemos construir, sino que también nos permite extraer la referencia del documento para el siguiente paso. Tenga en cuenta en mi consulta que estoy utilizando una cláusula 'where' de oslc para extraer solo mi registro de ejemplo. Además de esta publicación, necesitará un encabezado con la clave "apikey" y una clave API válida con acceso.  
‍

Ejemplo de consulta GET en Postman:
‍

https://mas.manage.demo.naviam.app/maximo/api/os/NVMPERSON?oslc.select=personid, displayname, doclinks{*}&oslc.where=personid="PHIL.RUNION"&lean=1

Qué hace esto:

• oslc.where=document="..." filtra un registro específico

• oslc.select= personid, displayname, doclinks{*} devuelve un par de campos de la persona y todos los campos disponibles de doclinks

• lean=1 elimina el ruido de los metadatos y simplifica la respuesta
  ‍

‍

En el objeto DOCLINKS puede ver la información de los adjuntos que podemos usar para extraer la imagen. Desde la carga útil de la respuesta, identifique el registro que contiene:

• El identificador interno del recurso

• El valor href, que representa el punto final del documento
  ‍

Este href es lo que utilizará en el siguiente paso.

Paso 3: Recuperar la imagen

Una vez que tenga la referencia del documento, puede llamar directamente al punto final del documento. Lo bueno de Postman es que puede tomar los datos brutos del documento en formato Base64 y visualizarlos. Si está utilizando otra herramienta, deberá procesar la salida en un archivo utilizable.  
‍

Ejemplo:

https://mas.manage.demo.naviam.app/maximo/api/os/m4m_doclinks/_MTYwNzc4L0F0dGFjaG1lbnRzLzM5NzE5L1BFUlNPTg--?oslc.select=documentdata&lean=1&inlinedoc=1

Parámetros clave:

• oslc.select=documentdata
  Devuelve el contenido binario del documento

• inlinedoc=1
  Asegura que los datos del documento se devuelvan en línea en la respuesta

• lean=1
  Mantiene la respuesta limpia y enfocada

Consideraciones comunes

Seguridad y autenticación

Asegúrese de que su llamada a la API incluya la autenticación adecuada, normalmente mediante una clave API o un token de sesión.

Rendimiento

Evite extraer documentos grandes en bloque. En su lugar:

• Filtrar DOCLINKS de forma precisa

• Recupere solo los documentos que necesite

Límites de tamaño de archivo

Los archivos adjuntos grandes pueden aumentar significativamente el tamaño de la respuesta. Considere la transmisión (streaming) o un manejo alternativo si es necesario.

Estructura del objeto

La estructura exacta del objeto puede variar según la configuración de la estructura de su objeto, pero el patrón se mantiene constante.

‍

‍

Este enfoque es sencillo una vez que se comprende la separación entre metadatos y contenido en Maximo. Es especialmente útil para:

• Integraciones que necesitan acceso a archivos adjuntos

• Componentes de interfaz de usuario personalizados que muestran imágenes

• Automatizaciones que procesan archivos cargados
  ‍

Si estás desarrollando con las API de MAS, este es un patrón que reutilizarás a menudo.

‍