IBM

SharePoint Secured Attachments in Maximo 9.2: OAuth 2.0, the DOCLINK_ Endpoint Convention, and the URL Conversion Script

Kevin Arhagba

Kevin Arhagba

— 7 min read
Share

The single most common document-management complaint in Maximo for the last decade has been: "We have our documents in SharePoint. Why is it so painful to attach a SharePoint file to a work order?" The answer has always involved either a copy-the-file-into-Maximo workaround (which created two sources of truth) or a clever-but-fragile web URL handler (which broke the moment the SharePoint permissions tightened up).

Maximo 9.2 closes this gap with a clean, supported pattern: native printing and viewing of secured SharePoint attachments, built on OAuth 2.0 against the Microsoft Graph API, a new DOCLINK_ endpoint convention in the End Points application, an automation-script-driven URL converter, and BIRT report integration. This article walks through the architecture and the configuration.

The four pieces of the pattern

1. OAuth 2.0 client registration in Maximo

The first piece is the OAuth 2.0 client. Maximo 9.2 uses OAuth 2.0 (RFC 6749) to talk to the Microsoft Graph API. The flow is the standard authorization code flow with client credentials — Maximo is registered as an OAuth client in your Azure tenant, and the operator stores the client credentials in Maximo's End Points application.

The configuration steps:

  1. In the Azure Portal, register a new application for Maximo in App registrations. Set the redirect URI to your Maximo base URL plus /oauth2/callback (e.g., https://maximo.yourcompany.com/oauth2/callback).
  2. Generate a client secret in the Certificates & secrets page. Note the secret value — it is only shown once.
  3. In API permissions, add the Microsoft Graph delegated permissions: Files.Read.All, Files.ReadWrite.All, Sites.Read.All, and User.Read. Grant admin consent.
  4. Note the tenant ID, the client ID, and the client secret — these are the three values Maximo needs.

In Maximo, go to the End Points application. The 9.2 release added a new action, Add/Modify OAuth Clients, that lets you register the OAuth client. The fields are:

  • OAuth Client Name — a friendly name (e.g., MS_GRAPH_SHAREPOINT)
  • Client ID — the Azure app registration's client ID
  • Client Secret — the secret value (stored encrypted in the Maximo database)
  • Token Endpoint — https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
  • Authorization Endpoint — https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize
  • Scope — https://graph.microsoft.com/.default

Save the OAuth client. Maximo will use the client credentials flow to obtain a token for the Graph API calls.

The second piece is the endpoint convention. Maximo 9.2 introduces a naming pattern for endpoints that handle document links: any endpoint whose name starts with DOCLINK_ is treated as a document-link endpoint, and the integration framework applies the document-link-specific processing to it.

The configuration:

  1. In the End Points application, create a new endpoint.
  2. Set the Endpoint Name to start with DOCLINK_ (e.g., DOCLINK_SHAREPOINT).
  3. Set the Handler to HTTP (the standard HTTP handler in the integration framework).
  4. Set the OAUTHCLIENT to the OAuth client you registered in step 1 (MS_GRAPH_SHAREPOINT).
  5. Set the Base URL to your SharePoint site (e.g., https://yourcompany.sharepoint.com).

The endpoint acts as the traffic controller. It defines the handler (HTTP), the authentication (the OAuth client), the base URL (the SharePoint site), and the URL conventions the document-link subsystem will use.

The DOCLINK_ prefix is the convention. Endpoints without the prefix are not treated as document-link endpoints, and the OAuth client, the URL conversion script, and the BIRT integration do not apply. This is the explicit way to opt in.

3. The URL conversion automation script

The third piece is the URL conversion automation script. This is the most clever part of the pattern. The problem is that a browser URL for a SharePoint file (what a user sees, with the site's URL and the document library path) is different from the API URL that Microsoft Graph expects (with the drive ID and the item ID). The conversion script bridges the gap.

Maximo 9.2 ships a framework for an automation script that runs when a user clicks "View Attachment" on a document link. The script:

  • Receives the browser URL and the document-link metadata as inputs.
  • Resolves the browser URL to a Microsoft Graph API URL (using a lookup table or a Graph API call to map the URL to the drive ID and item ID).
  • Returns the resolved API URL to the document-link subsystem.
  • The subsystem uses the API URL to fetch the file from SharePoint using the OAuth-authenticated Graph call.

The default script handles the common case (a URL in the standard SharePoint document library format). For more complex cases — a URL in a non-standard library, a URL in a subsite, a URL with query parameters that affect the resolution — the script can be customized.

The script launch point is the DOCLINK URL Converter script, with a launch point on the doclink.url.convert event. The script has access to the document-link record (the URL, the entity, the entity ID), the user session, and the OAuth client. The output is the resolved Graph API URL.

This is also the place to add audit logging — every URL conversion is a useful audit event for document access.

4. BIRT report integration

The fourth piece is the BIRT integration. The 9.2 release added a BIRT function that can resolve a document link to a Graph API URL at report-render time, so a BIRT report can include a live document link that points to the SharePoint file. The report developer adds the document-link field to the report layout, and the BIRT engine handles the resolution and the URL conversion.

The practical use cases:

  • A work order report that includes a "View Attached Manual" link. The link resolves to the SharePoint URL, and the user clicks through to the manual.
  • An asset report that includes a "View P&ID" link. The P&ID is stored in SharePoint, the report includes a link, and the user can click through without leaving the report context.
  • A PM record that includes a "View Procedure" link. The procedure is stored in SharePoint, the report includes a link, and the technician can view the procedure from the PM record.

The BIRT integration is the part that closes the gap between "the document is in SharePoint" and "the document is in the report." The report does not copy the document. The report includes a link that resolves at render time, and the link is a live SharePoint URL with the correct permissions applied.

The configuration walkthrough

Here is the end-to-end configuration, in order:

  1. Register the OAuth client in Azure. App registration, client secret, API permissions, admin consent.
  2. Create the OAuth client in Maximo. End Points → Add/Modify OAuth Clients → enter the tenant ID, client ID, client secret.
  3. Create the DOCLINK_ endpoint in Maximo. End Points → New → name = DOCLINK_SHAREPOINT, handler = HTTP, OAUTHCLIENT = MS_GRAPH_SHAREPOINT, base URL = https://yourcompany.sharepoint.com.
  4. Configure the URL conversion script. Automation Scripts → find the DOCLINK URL Converter script → review the launch point and the script logic → customize if needed.
  5. Create a document link in Manage. Work Order Tracking → Attachments → Document Link → URL = https://yourcompany.sharepoint.com/sites/eng/Shared Documents/Procedures/Pump-101-Disassembly.pdf → save.
  6. Test the resolution. Click "View Attachment" on the document link. The URL conversion script runs, the Graph API call is made with the OAuth token, and the file is fetched and rendered in the browser.
  7. Test the BIRT integration. Add the document link to a BIRT report layout, run the report, verify that the link resolves to the live SharePoint URL.
  8. Test the audit trail. Verify that the URL conversion script's audit log records every document access, with the user, the URL, and the resolution timestamp.

The security and compliance angle

The pattern is built around the assumption that the SharePoint documents are secured (the user needs to be authenticated to view them). The OAuth 2.0 flow is the right pattern for this, because the Maximo user is the principal in the Graph API call, and the SharePoint permissions apply.

The security boundaries to verify:

  • The OAuth client is stored encrypted in Maximo. The client secret is encrypted at rest. Verify the encryption is in place (the encryption key in the Maximo configuration).
  • The token is cached, not persisted. The OAuth access token is cached in memory for the token lifetime (typically 1 hour) and refreshed automatically. It is not written to the database.
  • The document-link subsystem honors the SharePoint permissions. The Graph API call is made with the user's token, and the SharePoint site permissions apply. A user who does not have access to the SharePoint file will receive a 403 from Graph, and Maximo will surface the error.
  • The audit log is complete. Every document access is logged. The audit log includes the user, the document link, the resolution URL, and the timestamp. The audit log is stored in the Maximo database and can be exported for compliance reporting.

What this pattern replaces

The patterns this replaces are the ones that have been causing pain for years:

  • The "copy the file into Maximo" pattern. The document is now in SharePoint, and the doclink is a live URL. There is no duplicate copy, no out-of-date copy, no storage overhead in Maximo.
  • The "anonymous SharePoint URL" pattern. The URL is now OAuth-authenticated. The SharePoint permissions apply. There is no "anyone with the link can view" exposure.
  • The "web URL handler" pattern. The conversion script is a supported, documented framework. There is no more custom Java code to maintain.
  • The "BIRT prints a broken link" pattern. The BIRT integration resolves the link at report-render time. The report includes a live, working URL.

The pattern is the right answer for the customer that has SharePoint as the document system of record, Maximo as the asset and work management system, and a security and compliance requirement that the documents be access-controlled at the SharePoint layer. For the first time, those three things can coexist without a workaround.

The failure modes and the mitigations

The pattern has three failure modes that the practitioner needs to be aware of:

  1. OAuth token expiration during a long-running report. If a BIRT report runs for longer than the OAuth token lifetime (1 hour), the token will expire mid-report. The mitigation is to set the report to run in batches, or to use a service principal with a longer-lived token.
  2. SharePoint URL changes when the file is moved. If a user moves the file in SharePoint, the document link in Maximo becomes stale. The mitigation is a periodic re-resolution job that walks the document links and updates the URLs.
  3. Graph API throttling. The Microsoft Graph API has rate limits, and a high-volume BIRT report run can hit the limit. The mitigation is to implement retry-with-backoff in the document-link subsystem, or to use a service principal with a higher rate limit.

These are operational issues, not architectural ones. The architectural pattern is correct; the operational tuning is the practitioner's job.

Read more