Preparing your data for field value recommendations

Before you can enable the AI configuration for field recommendations, you must prepare your training and inference data and create training and inference filters.

1. Choose an object structure.
   The object structure is a foundational part of an AI configuration. It determines all of the data that the model uses for training and inferencing. Select an object structure that represents the records that you want recommended values for, such as MXAPIWODETAIL.
2. Decide what data you will use for training and prepare that data.

   Within the chosen object structure, you must choose at least 20 records for the training data set. 10 of those records must contain one possible value type that you want AI to recommend. The other 10 records must contain another value type. For example, if you wanted AI to recommend work types, choose 10 work orders that contain one work type and 10 work orders that contain another work type.

   To decide what records to choose, consider the following best practices:

   • Use unique records. The training process filters out duplicate records of the same type, for example, duplicate purchase orders.
   • Use diverse records of the same type. Ideally, the records include a range of descriptions and address a range of problems but are all the same type of record, for example, all purchase orders.
   • Use records that have accurate instances of the values.
   • Ensure that each possible recommended value has an accurate description and details.
   • Ensure that each record has an accurate description.
   • Although the minimum is 20 records, the larger, more diverse, and accurate your training filter data is, the more likely the model can accurately recommend values. The ideal training filter contains 20 - 50 records per possible value.
3. Create the training and inference filters.

   Filters, also known as query definitions, determine what records are used for training or inferencing and what records have the value recommendation feature enabled. Create one filter for training and one filter for inferencing. All of the data that is included in the filter is used for the filter's respective process.

   These filters are defined as query definitions for the object structure that you chose in step 1. You use the same object structure for both filters, and then use the query definitions to specify a subset of data for each filter.

   1. In Maximo Manage, in the Object structures application, open the object structure.
   2. In the More actions menu, click Query definition.
   3. Click the plus (+) icon.
   4. In the Query Type field, select osclause.
   5. In the Query Clause Name field, specify a name for the filter.

      Ensure that the name indicates whether the filter is for training or inferencing and what AI configuration it is associated with.

   6. In the Query Clause field, specify a WHERE clause that retrieves the records that you want to use for training or inferencing.
      The following text is an example of a query clause that retrieves all EM and CM work orders.

      worktype in ('EM','CM')

      For the training filter, specify a clause that retrieves the records that you chose in step 1.

      For the inference filter, specify a clause that returns all of the records for which you want to enable the recommendation feature. To improve system performance, set an age limitation on the records. For example, if the training filter retrieves 20 EM and CM work orders, configure the inference filter to retrieve all CM and EM work orders in the last 30 days. The following text is an example of a query clause for an inference filter.

      worktype in ('EM', 'CM') and status in (select value from synonymdomain where domainid ='WOSTATUS' and maxvalue in ('WAPPR')) and reportdate > CURRENT DATE - 30 DAYS

   7. Click the Is Public? checkbox.
   8. Click OK.
   9. Repeat the steps to add the other filter.
4. Determine the attribute names for the following values. You must have the attribute names to complete step 4.
   • Each feature, or field, that can be compared to determine recommended values, for example, description and description_longdescription.
   • The unique attribute ID for the object for which inferencing is completed. For example, WORKORDERID is the unique attribute ID for the WORKORDER object.
   • The attribute name for the field that the model is recommending a value for. For example, if you want the model to recommend work types, determine the attribute name for work types.
   • The description attribute for the attribute name.
5. Create query templates for training and inferencing.
   For the object structure that the filters use, add a query template for training and a query template for inferencing. Query templates contain attributes. For AI configurations, the template defines the JSON structure for training data. AI Service uses the template to fetch the data.
   1. In Maximo Manage, in the Object Structures application, open the object structure.
   2. In the More actions menu, click Query Template.
   3. In the Query Templates for table, click New Row.
   4. In the Description field, specify a description that indicates that the query template is used for training or inferencing and what AI configuration it is associated with.
   5. In the Page Size field, specify 1,000 for training or 10 for inferencing.
   6. Select the Default Projection? checkbox.
   7. In the Query Template Attributes for table, add a row for each required attribute.
      For the training template, the table must contain the following attributes:

      • Each feature, or field, that can be compared to determine recommended values. Specify a comma-separated list.

        To specify a feature that is a child attribute of a single related object, use the following notation: relationship.attribute

        To specify a feature that is a child attribute of multiple related objects, use the following notation: rel.relationship{attribute}

      • The unique attribute ID for the object for which inferencing is completed. For example, WORKORDERID is the unique attribute ID for the WORKORDER object.
      • The field that the model is recommending a value for. For example, if you want the model to recommend work types, specify the attribute name for work types.
      • The description attribute for the attribute name. Use the following format: attribute_description

        If the target description is sourced from a related object, use the following format: relationship.description--attribute_description

        For more information about the notation, see Query template JSON examples.

      For inferencing, the table must contain the features and the unique attribute ID for the object.

6. Create an invocation channel for training.

   Invocation channels facilitate training and inferencing for the AI configuration. For more information about creating channels, see Creating invocation channels.

   1. In Maximo Manage, in the Invocation Channels application, search for and select the AITRAINWOPROBLEMCODE channel.
   2. In the More actions menu, click Duplicate Invocation Channel.
   3. In the Invocation Channel field, specify a unique name and description. Ensure that the name and description indicates that the channel is used to train AI models and which AI configuration it is used for.
   4. In the Endpoint field, ensure AIBROKERAPI is specified. If you edit any end point properties, ensure that the Override checkbox is selected.
   5. In the Request Object Structure field, select the object structure that you used for the inference and training filters. The object structure, in the invocation channel, is used to generate the compressed file for training and to fetch the data details for inferencing. Use the same object structure for both channels.
   6. In the Request Template field, select the query template for training that you created for the object structure.
   7. In the Request Processing Class field, ensure that com.ibm.tivoli.maximo.ai.AITrainReqExit is specified.
      Note: When you add an AI configuration, you can choose to specify a hierarchy path. If a hierarchy path is specified, the AITrainReqExit processing class transforms the request JSON to make the child object that is referred by the hierarchy path in to the root object of the JSON.

      For example, if an object structure contains PO as an object and POLINE as a child, and the hierarchy path is set to PO/POLINE, then the AITrainReqExit request processing class uses POLINE as the root object and removes the PO parent in the transformed JSON. The following text is an example structure:

      
      PO
       POLINE
       POLINE

      The following text is an example of an updated structure:

      
       POLINE
       POLINE

   8. In the Response Processing Class field, ensure that com.ibm.tivoli.maximo.ai.AITrainRespExit is specified.
7. Create an invocation channel for inferencing.
   1. In Maximo Manage, in the Invocation channels application, search for and select the AIINFWOPROBLEMCODE channel.
   2. In the More actions menu, click Duplicate Invocation Channel.
   3. In the Invocation Channel field, specify a unique name and description. Ensure that the name and description indicates that the channel is used for inferencing for AI models.
   4. In the Endpoint field, ensure AIBROKERAPI is specified. If you edit any end point properties, ensure that the Override checkbox is selected.
   5. In the Request Object Structure field, specify the object structure that you used for the inference filter.
   6. In the Request Template field, select the query template for inferencing that you created for the object structure.
   7. In the Request Processing Class field, ensure that com.ibm.tivoli.maximo.ai.AIINFReqExit is specified.
   8. In the Response Processing Class field, ensure that com.ibm.tivoli.maximo.ai.AIINFRespExit is specified.