Build an application-specific lookup with a Maximo automation script

A lookup is easy enough when every record uses the same selection rules. It gets more interesting when the same field needs to offer different records depending on the application using it.

In this example, a restriction record has a document-reference field. In the asset application, the lookup should show restriction documents attached to the current asset. In the location application, it should show restriction documents attached to the current location.

An attribute automation script with a Retrieve List launch point supplies the lookup object, filters and return-value mapping. The selection logic lives in the script rather than a table domain.

What the lookup returns

The lookup reads DOCLINKS records and copies their DOCUMENT value into DOCUMENTREFERENCE on the current RESTRICTION record. These are example custom object, attribute and application identifiers; substitute the actual names in your environment.

Only attachments with DOCTYPE = 'Restrictions' are included. The application determines which owner is allowed:

The application IDs are configuration values, not the labels displayed in navigation. LOCATION is the example application ID; LOCATIONS is the underlying location object/table name used in the filter.

Configure the attribute launch point

In Automation Scripts, create a Jython script with an attribute launch point on the object and attribute that hold the selected reference:

• Object: RESTRICTION.
• Attribute: DOCUMENTREFERENCE.
• Event: Retrieve List.
• Script and launch point name: DOCREFERENCELOOKUP.

Use your actual custom identifiers if they differ. The object must expose the ASSETNUM, LOCATION and SITEID values needed by the relevant branch. The colon-prefixed SQL bindings resolve against the current MBO; they do not automatically read an arbitrary parent application's record.

The classic UI also needs a lookup definition in lookups.xml and a corresponding lookup reference on the presentation control. Configure that lookup to display the document fields users need to recognise the correct attachment. The script supplies the rows; it does not define the dialog's columns. IBM describes these requirements in its attribute launch-point guide.

The script

The script below selects the filter for the current application and maps the selected document reference back to the restriction record:

# Application context.
appName = mbo.getThisMboSet().getParentApp()
 
# Lookup mapping.
relationObject = "DOCLINKS"
srcKeys = ["DOCUMENT"]
targetKeys = ["DOCUMENTREFERENCE"]
 
assetDocLinkWhere = """
OWNERTABLE = 'ASSET'
AND DOCTYPE = 'Restrictions'
AND EXISTS (
    SELECT
      NULL
    FROM
      ASSET
    WHERE
      ASSET.ASSETNUM = :ASSETNUM
      AND ASSET.SITEID = :SITEID
      AND ASSET.ASSETUID = DOCLINKS.OWNERID
)
""".strip()
 
locationDocLinkWhere = """
OWNERTABLE = 'LOCATIONS'
AND DOCTYPE = 'Restrictions'
AND EXISTS (
    SELECT
      NULL
    FROM
      LOCATIONS
    WHERE
      LOCATIONS.LOCATION = :LOCATION
      AND LOCATIONS.SITEID = :SITEID
      AND LOCATIONS.LOCATIONSID = DOCLINKS.OWNERID
)
""".strip()
 
# Application-specific filters.
if appName == "ASSET":
    listWhere = assetDocLinkWhere
    relationWhere = assetDocLinkWhere
elif appName == "LOCATION":
    listWhere = locationDocLinkWhere
    relationWhere = locationDocLinkWhere
else:
    listWhere = "1=2"
    relationWhere = "1=2"

Application context selects the filter

The first line reads the parent application from the current MBO set:

appName = mbo.getThisMboSet().getParentApp()

The script compares that value with the configured application IDs. In ASSET, it assigns the asset attachment filter. In LOCATION, it assigns the location attachment filter.

Both listWhere and relationWhere receive the same expression, keeping the list and relationship criteria aligned for this example. The fallback sets both to 1=2, an expression that cannot match a row. An unexpected or absent application context therefore returns an empty list rather than all restriction attachments.

This makes application context part of the behaviour. Test the actual MBO set used by your screen, especially if the field appears on a child table or dialog. Background processing and other callers may not supply the same parent application.

Mapping the selected value

The three mapping assignments are small but important:

relationObject = "DOCLINKS"
srcKeys = ["DOCUMENT"]
targetKeys = ["DOCUMENTREFERENCE"]

relationObject identifies the lookup object. The two arrays pair the source attribute with its destination: the selected row's DOCUMENT value is returned to the current record's DOCUMENTREFERENCE field. IBM's Retrieve List documentation explains the source-to-target mapping variables.

This stores a document reference, not a DOCLINKSID, attachment URL or file contents. Check whether DOCUMENT is sufficiently unambiguous for your design. If different attachment rows share a document value, that value alone will not distinguish them.

Why the filters use EXISTS

The outer filter starts with two restrictions: the attachment must belong to the expected owner table and have the required document type.

The asset branch then looks for an ASSET row matching the current asset number and site, with ASSETUID equal to the attachment's OWNERID. The location branch does the equivalent with LOCATION, SITEID and LOCATIONSID.

That matters because an attachment's OWNERID is the owning record's internal identifier. It is not the displayed asset number or location code. The subquery connects the business identifier on the restriction record to the internal identifier used by DOCLINKS.

Including SITEID also prevents the filter from matching the same asset number or location code in another site. OWNERTABLE distinguishes owner types whose internal numeric IDs might otherwise overlap.

SELECT NULL is intentional: EXISTS checks whether a matching row exists, so the projected value is not used. The multiline strings make the filters readable, while .strip() removes whitespace at their ends.

Check it in the application

Before relying on the lookup, verify the following in a non-production environment:

1. In the asset application, attach a document of type Restrictions to the selected asset and confirm it appears.
2. Confirm documents on another asset, another site or a location do not appear in that asset lookup.
3. Repeat the test in the location application, including a location code reused in another site.
4. Confirm attachments with a different document type are excluded.
5. Select a result and confirm its DOCUMENT value populates DOCUMENTREFERENCE.
6. Test missing asset/location values and an unsupported application context.
7. Type an invalid reference directly into the field and check the validation behaviour.

A filtered lookup is a selection aid, not a complete authorisation policy. Verify permissions and any required server-side validation for typed values, integrations and other entry points. Also check what should happen to an existing document reference if the restriction's asset or location changes.

This example was tested in Maximo 9.1. Configure the lookup definition and presentation control for your own application.

The result is one field with application-specific selection rules: assets see their restriction documents, locations see theirs, and unexpected contexts get no choices. The table domain can sit this one out.