Saving additional attributes when adding Attachments

Overview

• Mark attachments as default/primary during upload (e.g., default CAD drawing for an asset)
• Flag attachments for automated processing (e.g., photos requiring AI analysis)
• Capture document classification or scoring during upload
• Set custom metadata fields required by business processes

• Application must use the touch theme
• Basic understanding of Graphite XML components and event handlers
• Access to modify application XML and controller files
• Custom attributes must be valid DOCLINK fields in the object structure

Implementation

Step 1: Enable custom options in the attachment list

<attachment-list 
  id="attachmentList1" 
  datasource="attachmentds" 
  allow-naming="true"
  file-name-required="false" 
  file-desc-required="false"
  show-folder-list="false" 
  hide-when-empty="false" 
  is-editable="true"
Copy to clipboardCopied!

Step 2: Add custom controls using the custom-options slot

<attachment-list 
  id="attachmentList1" 
  datasource="attachmentds" 
  allow-naming="true"
  file-name-required="false" 
  file-desc-required="false"
  show-folder-list="false" 
  hide-when-empty="false" 
  is-editable="true"
Copy to clipboardCopied!

• Controls appear below the description field (or below folder list if enabled)
• Use on-change and on-change-arg for text-input, number-input, and checkbox
• Use on-toggle and on-toggle-arg for toggle controls
• The *-arg attribute specifies the DOCLINK attribute name to update

Step 3: Implement event handlers in the controller

/**
 * Handler for checkbox control - sets default flag
 * @param {string} attr - The DOCLINK attribute name (e.g., 'isdefault')
 * @param {Object} event - Event object with value property
 */
setAsDefault(attr, event) {
  const TAG = 'AttachmentCustomOptions';
  this.app.log.i(TAG, 'setAsDefault: ', attr + '=' + event?.value);
  
Copy to clipboardCopied!

• Toggle controls use event.target.checked (boolean)
• Other controls use event.value (string or number)
• Always call event.onUpdate(attr, value) to persist the value
• The attribute and value are included in the save payload automatically

Step 4: Ensure attributes are in the object structure

<maximo-datasource id="attachmentds" object-structure="MXAPIDOCLINKS">
  <schema>
    <attribute name="docinfoid" id="attr_001"/>
    <attribute name="description" id="attr_002"/>
    <attribute name="urlname" id="attr_003"/>
    <!-- Custom attributes for custom-options -->
    <attribute name="isdefault" id="attr_004"/>
    <attribute name="inferreq" id="attr_005"/>
    <attribute name="score" id="attr_006"/>
Copy to clipboardCopied!

Validation & Testing

1. Test custom controls display:

   • Navigate to a page with the configured attachment list
   • Click the “Add attachment” button
   • Expected Result: The upload dialog displays all custom controls below the description field

2. Test value capture:

   • Fill in the custom control values (check boxes, enter text, adjust numbers)
   • Select a file and complete the upload
   • Expected Result: The attachment is saved successfully

3. Test value persistence:

   • After upload, query the DOCLINK record in Maximo
   • Check the custom attribute values in the database
   • Expected Result: The values match what was entered in the custom controls

4. Test with different control types:

   • Upload multiple attachments with different control values
   • Verify each control type (checkbox, toggle, number, text) saves correctly
   • Expected Result: All control types persist their values properly

• Issue: Custom controls don’t appear in the upload dialog

  • Cause: The allow-naming attribute is not set to true
  • Solution: Add allow-naming="true" to the attachment-list component

• Issue: Values are not saved with the attachment

  • Cause: Missing event.onUpdate() call in the event handler
  • Solution: Ensure each handler calls event.onUpdate(attr, value)

• Issue: Attribute not found error when saving

  • Cause: Custom attribute is not in the object structure schema
  • Solution: Add the attribute to the datasource schema definition

• Issue: Toggle control doesn’t work correctly

  • Cause: Using event.value instead of event.target.checked
  • Solution: Toggle controls must use event.target.checked for the boolean value

Best Practices

• Use meaningful labels that clearly describe what each control does
• Set appropriate default values for controls to guide users
• Validate attribute names match exactly with DOCLINK fields in Maximo
• Use number-input with min/max constraints for bounded values
• Add logging in event handlers for troubleshooting

• Don’t use custom attributes that aren’t in the object structure
• Don’t forget to call event.onUpdate() in every handler
• Don’t mix up event signatures (toggle vs. other controls)
• Don’t add too many custom controls (keep UI simple and focused)
• Don’t use this feature without the touch theme

• Custom controls add minimal overhead to the upload process
• Keep the number of custom controls reasonable (3-5 maximum recommended)
• Avoid complex validation logic in event handlers

• Ensure users have appropriate permissions to update the custom DOCLINK attributes
• Validate input values if they affect security-sensitive fields
• Consider using domain validation in Maximo for restricted value lists

Related Resources

• Understanding Datasources - Learn about datasource configuration
• Graphite Components Overview - Basic Graphite component knowledge

• Performance considerations for mobile doclinks - Optimize attachment handling
• Default record data options - Set default values for records

• IBM Maximo Mobile Framework Documentation
• DOCLINKS Object Structure Reference

Additional Notes

• This feature requires Maximo Mobile Framework with touch theme support
• Verify your MAF version supports the custom-options slot
• Some older versions may have limited control type support

• Custom controls are optimized for touch interfaces
• Test on actual mobile devices to ensure proper rendering
• Consider screen size when adding multiple controls

• Use page state to dynamically show/hide controls based on other selections
• Combine with show-folder-list to organize attachments by folder and metadata
• Implement custom validation by checking values before calling event.onUpdate()
• Use the record-marker-field-name feature to visually highlight default attachments

• Enable debug logging: this.app.log.d(TAG, 'Debug message') in handlers
• Check browser console for JavaScript errors during upload
• Verify object structure includes all custom attributes using Maximo Integration Framework
• Test with a simple single control first, then add complexity