Opqo 22.10.0 introduces the ability to add configuration to define how to interpret/parse barcodes and QR codes that are scanned.

This includes:

• Defining which Maximo fields should be searched when a single value barcode is scanned
• Defining how to parse fields from more complex multi-value barcodes.  

Scanning can be configured for the following searches:

• Work Order - used as part of assigned work order search
  
• Location and Asset - used when creating inspections and quick reports, and reporting issues
• Inventory - used when browsing and issuing inventory
• Inventory Balance - used when counting inventory
• Countbook Line - used when performing countbook counts
• Material Usage Transaction - used in when returning inventory
• Purchase Order - used when performing inventory receiving 

Default Scanning Configuration

The default scanning configuration is as follows:

Work Order Scanning

Work Order scanning is a little different to the other types of scanning, in that typically it is expected that the barcode/QR code is for an associated asset or location, rather than a work order property.

When asset or location configurations/properties are matched to a scan, these will match work orders with a matching asset/location at the following levels:

• Directly on the work order
• On tasks
• On child work orders
• On multi-asset/location records.

To simply the configuration, work order scanning can be configured to re-use the asset or location scanning configuration (it uses the asset configuration by default), or if necessary, a work order specific configuration can be specified.

See the Work Order Scanning Configuration section below for more details.

Specifying Custom Scanning Configuration

Each of the default configurations listed above can be replaced with a custom configuration.  These configurations are specified in the general section of the STAMCONFIG script.  

More detail on modifying the STAMCONFIG script can be found in the article: Configuration Overview. 

Concepts

A scan configuration defines one or more barcode formats, where a barcode format may be one of:

• A single value format, where the entire value contained in the barcode is used. This may then be used to search against one or more fields.
• A parsed format, where one or more known fields are parsed from the scanned barcode. These fields and values are used to search, returning results that match all fields/values.

Where a scan configuration contains multiple formats, the formats are checked in sequence, first for a match against the scanned barcode value and secondly for results in Maximo.  The results are returned from the first matching format that returns a non-empty result set from Maximo.

A parsed format consists of one or more field configurations that define the field name and the mechanism for parsing the field value from the scanned barcode.  The following mechanisms are supported:

• JSON path expressions: for example, a QR code that contains data in JSON format.
• Regular expressions: for example, matching values by prefix or format
• Delimited fields: for example, a barcode that contains comma-separated values

Parsed formats are evaluated against the scanned barcode value, and are only considered a match if all fields are successfully populated from the barcode value.

Configuration

The scan configurations are specified within the scan/parsers section of the general section of the STAUTOSCRIPT.STAMCONFIG automation script in the Maximo environment:

appConfig = {
  "general": {
    ...
    "scan": {
      "parsers": {
        ...
      }
    }
  }
}

Each configuration is a named object within this section:

The named object contains a formats array, containing the scanning formats that define the configuration.

The following configuration snippet contains an example scanning configuration for asset, which will be used to demonstrate the different format types.

appConfig = {
  "general": {
    ...
    "scan": {
      "parsers": {
        "asset": {
          "formats": [
            {
              "fields": [
                {
                  "fieldName": "siteid",
                  "jsonpath": "$.siteid",
                },
                {
                  "fieldName": "assetnum",
                  "jsonpath": "$.assetnum",
                }
              ],
            },
            {            
              "fields": [
                {
                  "fieldName": "assettag",
                  "expression": "A([\\w\\d]+)",
                }
              ],
            },
            {
              "fields": [
                {
                  "fieldName": "siteid",
                  "delimiter": ",",
                  "index": 0,
                },
                {
                  "fieldName": "assetnum",
                  "delimiter": ",",
                  "index": 1,
                }
              ],
            },
            {
              "fieldNames": ["assetnum", "assettag", "serialnum", "location"]
            }
          ]
        }
      }
    }
  }
}

This configuration defines four scan formats, one of each of the different supported types:

1. JSON scan format
2. Regular Expression scan format
3. Delimited scan format
4. Single value format, searching multiple fields

Each of these is described in more detail, below.

JSON Scan Format

This scan format expects the barcode value to contain a stringified JSON object, with siteid and assetnum properties.  If this is successfully matched, and values obtained for siteid and assetnum, it will perform a search for an asset matching that SITEID and ASSETNUM.

{
  "fields": [
    {
      "fieldName": "siteid",
      "jsonpath": "$.siteid",
    },
    {
      "fieldName": "assetnum",
      "jsonpath": "$.assetnum",
    }
  ]
}

An example barcode value:

{
  "siteid": "BEDFORD",
  "assetnum": "1001",
  "location": "MOFLOOR1"
}

Properties are defined using JSONPath notation, an must include the $ symbol denoting the root of the JSON document.  Further information on JSONPath syntax can be found here.

Regular Expression Scan Format

This scan format contains a single scan field, that defines a regular expression to extract a value for ASSETTAG, where the asset tag has an 'A' prefix.  If this is successfully matches, it will perform a search for an asset with that ASSETTAG.

{            
  "fields": [
    {
      "fieldName": "assettag",
      "expression": "A([\w\d]+)",
    }
  ]
}

In this example, the 'A' prefix is discarded, and the value after the prefix is used.

e.g. for a barcode value of A40056R5, the asset tag extracted is 40056R5.

Delimited Scan Format

This scan format contains two scan fields, that will match a barcode with two or more comma separated values.  The first value is the siteid, and the second value is the assetnum.  If this is successfully matches, it will perform a search for an asset matching that SITEID and ASSETNUM.

{
  "fields": [
    {
      "fieldName": "siteid",
      "delimiter": ",",
      "index": 0,
    },
    {
      "fieldName": "assetnum",
      "delimiter": ",",
      "index": 1,
    }
  ]
}

e.g. for a barcode value of BEDFORD,1001,MOFLOOR1 the SITEID is BEDFORD and the ASSETNUM is 1001

Single Value Format, Multiple Search Fields

This scan format will use the entire value of the barcode, and will perform searches in turn matching this value against the asset ASSETNUM, ASSETTAG, SERIALNUM and LOCATION.

{
    "fieldNames": ["assetnum", "assettag", "serialnum", "location"]
}

The first non-empty result set will be the returned values.

Work Order Scanning Configuration

In addition to the scanning configuration options described above, work order scanning can be configured to re-use the asset or location scan configurations.  This avoids having to duplicate the scanning configuration in the common case where assets or locations are tagged.

Configuring work order scanning to use the asset scan configuration (the default):

appConfig = {
  "general": {
    ...
    "scan": {
      "parsers": {
        "workorder": "asset"
      }
    }
  }
}

appConfig = {
  "general": {
    ...
    "scan": {
      "parsers": {
        "workorder": "location"
      }
    }
  }
}

Configuring work order scanning to use a work order specific scan configuration:

appConfig = {
  "general": {
    ...
    "scan": {
      "parsers": {
        "workorder": {
          "formats": [
            {
              "fieldNames": ["asset.assettag", "location.location", "wonum"]
            }
          ]
        }
      }
    }
  }
}

Note that in the above example, even though the ASSETTAG and LOCATION are only specified at the top level (directly on the work order), the scan search will still match these values on tasks, child work orders and multi-asset/location records.

Examples of common configuration

I have inventory barcodes deployed that are single-value, for both items and bins

The following configuration adds support for inventory and inventory balances, that will first search for matching ITEMNUM, and then BINNUM.

Note the use of the relationship 'dot' notation for the BINNUM search for INVENTORY.  This will match any INVENTORY record with an INVBALANCES record with the BINNUM.

appConfig = {
  "general": {
    ...
    "scan": {
      "parsers": {
        "inventory": {
          "formats": [
            {
              "fieldNames": ["itemnum", "invbalances.binnum"]
            }
          ]
        },
        "invbalance": {
          "formats": [
            {
              "fieldNames": ["itemnum", "binnum"]
            }
          ]
        }
      }
    }
  }
}