In Maximo Application Suite, werden Dokumente und Bilder als Anhänge gespeichert und über DOCLINKS verknüpft. Während dies in der Benutzeroberfläche unkompliziert ist, ist das programmatische Abrufen dieser Anhänge weniger offensichtlich.
‍

Dieser Beitrag erläutert ein einfaches Muster zur Verwendung der REST API, um:
‍

1. Ein Dokument über DOCLINKS

2. Den eigentlichen Binärinhalt abrufen, einschließlich Bildern

Den Ablauf verstehen

Maximo speichert Dokumentbinärdateien nicht direkt in den Hauptgeschäftsobjekten. Stattdessen:

• Das DOCLINKS-Objekt speichert Metadaten zu Anhängen, die Dateien und Datensätze verknüpfen

• Das DOCINFO repräsentiert den eigentlichen Dateinhalt und wird über einen Dokument-Endpunkt abgerufen
  ‍
  ‍

Aus diesem Grund umfasst der Prozess immer zwei Schritte:

1. DOCLINKS abfragen, um den Anhang zu identifizieren

2. Verwenden Sie den zurückgegebenen Bezeichner, um den Inhalt abzurufen

Mein Szenario

In Maximo habe ich mein Porträtfoto als Anhang zu meinen Personendatensätzen hinzugefügt. Mein Personendatensatz ist für dieses Beispiel PHIL.RUNION. Im Rahmen dieses Beispiels werde ich die Objektstruktur MXPERSON verwenden, um mein Porträtfoto aus meinem Personendatensatz mithilfe der REST-API und Postman.

Voraussetzungen

• Zugriff auf die Objektstruktur in Manage haben

• Einen Manage API-Schlüssel für Ihren Benutzer haben

Schritt 1: Eine Objektstruktur einrichten

Ich beginne mit der Objektstruktur MXPERSON, dupliziere sie und füge das DOCLINKS-Objekt als Quellobjekt hinzu. Sie können vorgefertigte Objektstrukturen verwenden, wenn diese bereits das DOCLINKS-Quellobjekt enthalten.  

• Duplizieren Sie die MXPERSON-Objektstruktur in Manage

• Fügen Sie DOCLINKS als Quellobjekt mit Beziehung zum Hauptobjekt hinzu

• Konfigurieren Sie den Sicherheitszugriff für die Objektstruktur

Schritt 2: Postman verwenden, um Ihren Datensatz abzurufen

Als Nächstes erstelle ich eine grundlegende REST-Abfrage in Postman, um meinen Personendatensatz abzurufen. Dies stellt sowohl eine Verbindung her, auf der wir aufbauen können, als auch ermöglicht es uns, die Dokumentreferenz für den nächsten Schritt abzurufen. Beachten Sie in meiner Abfrage, dass ich eine OSLC-WHERE-Klausel verwende, um nur meinen Beispieldatensatz abzurufen. Zusätzlich zu diesem Beitrag benötigen Sie einen Header mit dem Schlüssel „apikey“ und einen gültigen API-Schlüssel mit entsprechenden Zugriffsrechten.  
‍

Beispiel einer GET-Abfrage in Postman:
‍

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

Was dies bewirkt:

• oslc.where=document="..." filtert nach einem bestimmten Datensatz

• oslc.select= personid, displayname, doclinks{*} gibt einige Felder von person und alle verfügbaren Felder von doclinks zurück

• lean=1 entfernt unnötige Metadaten und vereinfacht die Antwort
  ‍

‍

Im DOCLINKS-Objekt sehen Sie die Anhangsinformationen, die wir verwenden können, um das Bild abzurufen. Identifizieren Sie aus der Antwortnutzlast den Datensatz, der Folgendes enthält:

• Der interne Ressourcenbezeichner

• Der href-Wert, der den Dokument-Endpunkt darstellt
  ‍

Diesen href werden Sie im nächsten Schritt verwenden.

Schritt 3: Bild abrufen

Sobald Sie die Dokumentreferenz haben, können Sie den Dokument-Endpunkt direkt aufrufen. Das Praktische an Postman ist, dass es die Rohdaten des Dokuments im Base64-Format entgegennehmen und visualisieren kann. Wenn Sie ein anderes Tool verwenden, müssen Sie die Ausgabe in eine nutzbare Datei umwandeln.  
‍

Beispiel:

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

Wichtige Parameter:

• oslc.select=documentdata
  Gibt den binären Inhalt des Dokuments zurück

• inlinedoc=1
  Stellt sicher, dass die Dokumentdaten inline in der Antwort zurückgegeben werden

• lean=1
  Hält die Antwort übersichtlich und zielgerichtet

Allgemeine Hinweise

Sicherheit und Authentifizierung

Stellen Sie sicher, dass Ihr API-Aufruf eine ordnungsgemäße Authentifizierung enthält, typischerweise über einen API-Schlüssel oder ein Session-Token.

Leistung

Vermeiden Sie das massenhafte Abrufen großer Dokumente. Stattdessen:

• Filtern DOCLINKS gezielt

• Rufen Sie nur die Dokumente ab, die Sie benötigen

Dateigrößenbeschränkungen

Große Anhänge können die Antwortgröße erheblich erhöhen. Erwägen Sie bei Bedarf Streaming oder eine alternative Handhabung.

Objektstruktur

Die genaue Objektstruktur kann je nach Konfiguration Ihrer Objektstruktur variieren, das Muster bleibt jedoch konsistent.

‍

‍

Dieser Ansatz ist einfach, sobald Sie die Trennung zwischen Metadaten und Inhalt in Maximo verstanden haben. Er ist besonders nützlich für:

• Integrationen, die Anhangzugriff benötigen

• Benutzerdefinierte UI-Komponenten, die Bilder anzeigen

• Automatisierungen, die hochgeladene Dateien verarbeiten
  ‍

Wenn Sie mit MAS APIs arbeiten, werden Sie dieses Muster häufig wiederverwenden.

‍