Charger des données par l'API REST de Maximo (MAS 9)

Authentification par clé d'API

Sur MAS 9, créez un utilisateur d'intégration dédié, donnez-lui les groupes de sécurité nécessaires, puis générez une clé d'API pour cet utilisateur dans Manage. Chaque requête la porte dans l'en-tête :

GET /maximo/api/os/mxapiasset?lean=1&oslc.select=assetnum,siteid,status&oslc.pageSize=10
Host: manage.votre-domaine.com
apikey: <clé d'API>

Le paramètre lean=1 supprime les préfixes d'espace de noms dans le JSON et rend les réponses plus simples à lire. Ne stockez jamais la clé dans un fichier partagé : elle donne les droits de l'utilisateur d'intégration à quiconque la possède.

Créer un enregistrement

POST /maximo/api/os/mxapiasset?lean=1
apikey: <clé d'API>
Content-Type: application/json
properties: assetnum,siteid

{"assetnum": "PMP-1001", "siteid": "BEDFORD", "description": "Pompe de relevage",
 "location": "BR300", "status": "NOT READY"}

L'en-tête properties demande à Maximo de renvoyer les attributs indiqués de l'enregistrement créé, ce qui permet de contrôler la création sans second appel.

Mettre à jour et faire un upsert

La mise à jour d'un enregistrement connu passe par son URI de ressource et l'en-tête x-method-override: PATCH. Pour un chargement rejouable, l'upsert est plus pratique :

POST /maximo/api/os/mxapiasset?lean=1
apikey: <clé d'API>
x-method-override: SYNC
patchtype: MERGE
Content-Type: application/json

{"assetnum": "PMP-1001", "siteid": "BEDFORD", "description": "Pompe de relevage n°1"}

Avec SYNC, Maximo crée l'enregistrement s'il n'existe pas et le met à jour sinon. Avec patchtype: MERGE, les objets enfants absents du message sont conservés au lieu d'être supprimés. C'est le comportement de l'action AddChange du MIF (voir le guide MIF).

Charger en masse : les appels groupés

Un appel par enregistrement est trop lent au-delà de quelques milliers de lignes. L'en-tête x-method-override: BULK permet d'envoyer un tableau d'enregistrements dans une seule requête, chacun avec ses propres métadonnées :

POST /maximo/api/os/mxapiasset?lean=1
apikey: <clé d'API>
x-method-override: BULK
Content-Type: application/json

[
  {"_data": {"assetnum": "PMP-1001", "siteid": "BEDFORD", "description": "Pompe 1"},
   "_meta": {"method": "SYNC", "patchtype": "MERGE"}},
  {"_data": {"assetnum": "PMP-1002", "siteid": "BEDFORD", "description": "Pompe 2"},
   "_meta": {"method": "SYNC", "patchtype": "MERGE"}}
]

La réponse est un tableau : une entrée par enregistrement, avec son propre statut. Un appel qui répond 200 peut contenir des lignes en erreur. Il faut donc lire chaque entrée, consigner les erreurs ligne par ligne et ne rejouer que celles-ci.

Débit, lots et reprise

• Taille des lots : commencez petit, mesurez, puis augmentez tant que le temps de réponse et le taux d'erreurs restent stables.
• Parallélisme : quelques flux simultanés accélèrent le chargement, mais saturent vite le serveur Manage et ses règles (scripts d'automatisation, files).
• Reprise : consignez quelles lignes ont été acquittées. Après une coupure, reprenez à la première ligne non acquittée ; l'upsert garantit qu'un renvoi ne crée pas de doublon.
• Fenêtre : chargez les gros volumes hors des heures de production, et prévenez l'équipe qui exploite MAS.

Relire pour contrôler

L'API sert aussi à prouver le résultat : une requête filtrée par oslc.where compte les enregistrements présents et compare leurs attributs au fichier source.

GET /maximo/api/os/mxapiasset?lean=1&oslc.where=siteid="BEDFORD"&count=1
apikey: <clé d'API>

Le guide contrôle qualité et réconciliation détaille cette relecture.

Erreurs fréquentes avec l'API REST

• 401 ou 403 : clé invalide, ou utilisateur sans droit sur l'application ou le site.
• Attribut ignoré : absent de l'object structure ; ajoutez-le ou changez d'object structure.
• Erreur métier BMXAA… : règle Maximo (valeur hors liste, statut interdit, référence absente) ; le message renvoyé indique l'attribut en cause.
• Nombres et dates mal typés : envoyez des nombres JSON (pas des chaînes au format local avec virgule) et des dates ISO 8601.
• Réponse HTML au lieu de JSON : redirection d'authentification (SSO) ou passerelle intermédiaire ; l'appel doit être retenté, pas compté comme un succès.

Questions fréquentes