Update doclinks to improve the performance of mobile data download for workorders
This guide instructs how to create and use a new doclinks relationship in mobile to better perform the workorder list download.
Note:
- This guide includes changes in MXAPIWODETAIL object structure. That can affect other APIs as well, consuming the object structure.
- Direct database changes are also included in the guide. Therefore, before carrying out these actions, the proper best practices should be followed, such as backing up the database beforehand and implementing the modification in the development environment first
Are you on Maximo 9.2?Version 9.2 ships an out-of-the-box fix for this problem — no manual relationship or
app.xml changes are required. See the
9.2 Out-of-the-Box Fix section below.
If you are on
9.1 or earlier, continue with the manual steps below.
9.2 Out-of-the-Box Fix — Separate Mobile and Manage Doclinks Relationships
Background
Prior to 9.2, the DOCLINKS relationship on workorder family objects served both the browser-based Manage UI and Maximo Mobile with a single SQL where clause. This made it impossible to independently tune mobile download performance without affecting Manage UI query performance — and vice versa.
Maximo 9.2 resolves this by splitting the single DOCLINKS relationship into two purpose-built relationships on four objects: WORKORDER, WOACTIVITY, WORELEASE, and WOCHANGE.
What Changed
- MOBILE_DOCLINKS — A new, simplified relationship with a where clause optimised specifically for mobile download performance. Used when Maximo Mobile is running on a device (
mobile=1).
- MANAGE_DOCLINKS — Cloned from the existing
DOCLINKS relationship (including any where clause customisations customers had already made). Used for all browser-based Manage UI access.
- The existing DOCLINKS relationship is updated to use an MBO method reference (
mbomethod:getDoclinksSet) that programmatically delegates to the appropriate relationship at runtime based on context.
How Context Detection Works
| Context |
Relationship Used |
Optimised For |
Maximo Mobile on device (mobile=1) |
MOBILE_DOCLINKS |
Fast mobile data download |
Browser-based Manage UI (no mobile param, or mobile≠1) |
MANAGE_DOCLINKS |
Manage UI responsiveness |
Note: Users accessing the same Graphite application from a browser will continue to use MANAGE_DOCLINKS, so there is no performance regression in the UI.
Affected Objects
The changes are applied to all four objects in the workorder family. Because WOACTIVITY, WORELEASE, and WOCHANGE all extend WORKORDER, the getDoclinksSet() method is implemented once on the WORKORDER MBO class and automatically inherited by the child objects.
Customising Doclinks in 9.2
The two new relationships give customers independent customisation points:
- To change which attachments are downloaded to mobile devices — modify the where clause on MOBILE_DOCLINKS.
- To change which attachments appear in the Manage UI — modify the where clause on MANAGE_DOCLINKS.
Any where clause customisations that existed on the original DOCLINKS relationship prior to upgrading to 9.2 are automatically migrated to MANAGE_DOCLINKS.
System Property: mxe.doclinks.useManageOnly
| Property |
Type |
Default |
Description |
mxe.doclinks.useManageOnly |
Boolean |
false |
When false (recommended default), mobile contexts use MOBILE_DOCLINKS and browser contexts use MANAGE_DOCLINKS. Set to true to force all contexts — including mobile — to use MANAGE_DOCLINKS. |
Recommendation: Leave mxe.doclinks.useManageOnly set to false to benefit from the mobile performance optimisation. Only set it to true if you have a specific requirement for mobile and Manage UI to always use the same doclinks query.
Manual Steps — For Maximo 9.1 and Earlier
If you are on Maximo 9.1 or an earlier version, follow the steps below to manually create an optimised doclinks relationship for mobile.
Step 1: In this step, we will create a new relationship that downloads only the workorder's doclinks and attachments on mobile
1. Go to the database configuration application
2. Search for WORKORDER and select it
3. Go to relationships
4. Create a new relationship
5. Name it MOBILEDOCLINK
6. Select DOCLINKS for Child Object field
7. Set the where clause to
ownertable='WORKORDER' and ownerid=:workorderid
This includes only the workorder’s attachment. You can alter this query (Where clause) to add more objects based on usage. Here is an example of how we can add attachment data for Assets in the same query.
doclinksid in (select doclinksid from doclinks where (ownertable='WORKORDER' and ownerid=:workorderid) UNION ALL select doclinksid from doclinks where (ownertable='ASSET' and ownerid in (select assetuid from asset where assetnum=:assetnum and siteid=:siteid)))
Adding here the Out of the Box doclink relationship to refer to build your custom query. Remove the UNION ALL section for the object you don't want its attachment to download on mobile.
doclinksid in (select doclinksid from doclinks where (ownertable='WORKORDER' and ownerid=:workorderid) UNION ALL select doclinksid from doclinks where (ownertable='WORKORDER' and ownerid in (select workorderid from workorder where parent=:wonum and istask=1 and siteid=:siteid)) UNION ALL select doclinksid from doclinks where (ownertable='ASSET' and ownerid in (select assetuid from asset where assetnum=:assetnum and siteid=:siteid)) UNION ALL select doclinksid from doclinks where (ownertable='LOCATIONS' and ownerid in (select locationsid from locations where location=:location and siteid=:siteid)) UNION ALL select doclinksid from doclinks where (ownertable='JOBPLAN' and ownerid in (select jobplanid from jobplan where jpnum=:jpnum and (siteid is null or siteid=:siteid) and pluscrevnum =:pluscjprevnum) ) UNION ALL select doclinksid from doclinks where (ownertable='PM' and ownerid in (select pmuid from pm where pmnum=:pmnum and siteid=:siteid)) UNION ALL select doclinksid from doclinks where (ownertable='SAFETYPLAN' and ownerid in (select safetyplanuid from safetyplan,wosafetyplan where safetyplan.safetyplanid=wosafetyplan.safetyplanid and wosafetyplan.wonum=:wonum and wosafetyplan.siteid=:siteid)) UNION ALL select doclinksid from doclinks where (ownertable in ('SR','INCIDENT','PROBLEM') and ownerid in (select ticketuid from ticket,relatedrecord where ticketid=recordkey and ticket.class = relatedrecord.class and relatedrecclass=:woclass and relatedreckey=:wonum and relatedrecsiteid=:siteid)) UNION ALL select doclinksid from doclinks where (ownertable in ('WOCHANGE','WORELEASE','WOACTIVITY') and ownerid in (select workorderid from workorder,relatedrecord where wonum=recordkey and workorder.woclass = relatedrecord.class and relatedrecclass=:woclass and relatedreckey=:wonum and relatedrecsiteid=:siteid)) UNION ALL select doclinksid from doclinks where (ownertable='COMMLOG' and ownerid in (select commloguid from commlog where ownerid=:workorderid and ownertable in (:&synonymlist&_WOCLASS[ACTIVITY,CHANGE,RELEASE,WORKORDER]))) UNION ALL select doclinksid from doclinks where (ownertable='SLA' and ownerid in (select slaid from sla,slarecords,workorder where sla.slanum=slarecords.slanum and slarecords.ownerid=workorder.workorderid and sla.objectname='WORKORDER' and slarecords.ownertable='WORKORDER' and workorder.wonum=:wonum)) UNION ALL select doclinksid from doclinks where (ownertable='PLUSDSPLAN' and ownerid in (select plusdsplanid from plusdsplan where (siteid is null or siteid=:siteid) and status in (select value from synonymdomain where (siteid is null or siteid=:siteid) and domainid = 'PLUSCDSSTATUS' and maxvalue = 'APPR') and dsplannum in (select dsplannum from pluscwods where wonum=:wonum and siteid=:siteid))))
Step 2: Now we can update the object structure to utilise the newly created relationship by running this database query on your database
update MAXINTOBJDETAIL SET RELATION='MOBILEDOCLINK' where INTOBJECTNAME='MXAPIWODETAIL' and RELATION='DOCLINKS' and HIERARCHYPATH='WORKORDER/DOCLINKS'
Step 3: Replace the doclink relationship with the new relationship MOBILEDOCLINK everywhere
In app.xml
1. In the example below, observe the relationship attribute. Change this line
<maximo-datasource id="attachmentListDS" attachment="true" page-size="250" relationship="doclinks" selection-mode="none">
Change to
<maximo-datasource id="attachmentListDS" attachment="true" page-size="250" relationship="MOBILEDOCLINK" selection-mode="none"/>
2.
<maximo-datasource id="signatureAttachment" can-load="{page.state.canLoadWoDetailsChilds}" attachment="true" relationship="doclinks" selection-mode="none" notify-when-parent-loads="true">
Change to
<maximo-datasource id="signatureAttachment" can-load="{page.state.canLoadWoDetailsChilds}" attachment="true" relationship="MOBILEDOCLINK" selection-mode="none" notify-when-parent-loads="true">
3. in woDetailResource datasource, change attribute from
<attribute name="doclinks" id="r_kd9">
to
<attribute name="mobiledoclink" id="r_kd9">
Step 4: Enhancing performance further by adding a database index
Add a new index in your database to improve doclink queries further, if it does not already exist
create index DOCLINKS_OWNERID_IDX_TEST on DOCLINKS ("DOCLINKSID","OWNERID", "OWNERTABLE");
Doclinks for WOACTIVITY (Tasks)
Step 1: Same as the above procedure, doclinks for the WOACTIVITY object can also be simplified as below
1. Go to the database configuration application
2. Search for woactivity and select it
3. Go to relationships
4. Create a new relationship
5. Name it MOBILEDOCLINK
6. Select DOCLINKS for the Child Object field
7. Set the where clause to
ownertable='WOACTIVITY' and ownerid=:workorderid
Step 2: Now we need to update the object structure to utilise the newly created relationship by running this database query on your database
update MAXINTOBJDETAIL SET RELATION='MOBILEDOCLINK' where INTOBJECTNAME='MXAPIWODETAIL' and RELATION='DOCLINKS' and HIERARCHYPATH='WORKORDER/WOACTIVITY/DOCLINKS' and RELATION='DOCLINKS';
Note: If you are not using attachments in Tasks of workorder on Mobile, it is better to remove them altogether. This will also make a good difference in performance.
1. Remove the below attribute from woPlanTaskDetailds and woPlanTaskDetaildsSelected datasources
<attribute name="doclinks{*}"/>
2. Remove the below datalist (id- q439v) part for UI removal
Additional Resources:
Maximo Mobile - Performance optimization#MaximoMobile #Technician #MobileTechnician #MobileDataDownload #MobileDocLinks #DocLinks #MaximoDocLinks #Performance #CheckForUpdates