Guide - MES Core

The Enterprise Framework plugin is a special dependency. This plugin was developed in conjunction with this MES application. The framework provides much of the 'enterprise' level functionality such as customization, standard GUIs and API support.

This module conforms to the Enterprise Framework coding standards.

Controls overall shop floor actions and manages demand flow on the floor.

Designs products and shop floor processes.

Performs most shop floor production, but can’t configure the shop floor or affect production outside of the local area.

A 'super' operator that does setup or works as a lead over a group of operators.

A typical dashboard has a number of dashboard activities displayed at a given time. Your application may need to coordinate behavior between these activities. For example, a selection list may need to inform another activity that the user changed the selection. Dashboard Events are used to allow your activities to communicate these type of changes.

The important events are:

uri: /work/completeActivity

This Complete activity is a Non-GUI Activity . This means it normally does not display a GUI and just performs the complete action. This activity works with the WorkController complete() method to perform the action.

The complete activity uses the Order/LSN parameter from the Work Center Selection activity and attempts to complete the work on it. Any errors are displayed in the dashboard’s message area.

uri: /work/startActivity

This Start activity is a Non-GUI Activity . This means it normally does not display a GUI and just performs the start action. This activity works with the WorkController start() method to perform the action.

The start activity uses the Order/LSN parameter from the Work Center Selection activity and attempts to start the work on it. Any errors are displayed in the dashboard’s message area.

uri: /work/reverseStartActivity

This Reverse Start activity is a Non-GUI Activity . This means it normally does not display a GUI and just performs the reverse start action. This activity works with the WorkController reverseStart() method to perform the action.

The reverse start activity uses the Order/LSN parameter from the Work Center Selection activity and attempts to reverse the start on it. Any errors are displayed in the dashboard’s message area.

uri: /work/reverseCompleteActivity

This Reverse Complete activity is a Non-GUI Activity . This means it normally does not display a GUI and just performs the reverse complete action. This activity works with the WorkController reverseComplete() method to perform the action.

The reverse complete activity uses the Order/LSN parameter from the Work Center Selection activity and attempts to reverse the complete on it. Any errors are displayed in the dashboard’s message area.

This reverse action will mark the Order/LSN as not done and issue a negative ProductionLog record. This action also places the Qty back in queue. It does not perform a start on the qty.

uri: /selection/workCenterSelection

This Work Center Selection activity is designed to be used in the primary section (top) of the dashboard and will allow the operators to select the work center they are working in and enter an order or LSN to process. The buttons that can be added to this activity will let the operator perform common actions on the entered work center, order or LSN.

In this dashboard activity, the operator can change the work center by clicking on the work center. This will open a dialog that lets the operator select the work center they are working in. This work center is retained and used as the default the next time the user uses this dashboard.

uri: /workList/workListActivity

This Work List activity is used to display active or queued work for the operator. The current Work Center (Work Center Selection) is used to filter this work to manageable level, but it is not required.

As the operator selects entries, the current selection is coordinated with the selection activity to keep the actions in synch.

There are a number of object diagrams to show you the relationships between various objects. These follow a general shape and color scheme as shown below:

Most top-level objects have a primary key field that is generally referred to as the record’s 'name'. This is usually the primary key for the record. Most objects have just one primary key field. For example, Order has a primary key field 'order'. This field must be unique in most cases. No other Order can have the same order value.

SimpleMES uses the term 'name' as the record’s identifier, as the user sees it. SimpleMES uses this 'name' term to avoid confusion with the ID used in the database.

Some ERP systems use the term 'Internal Reference'. This is the same as the 'name' in SimpleMES.

Most top-level objects have a 'title'. This is normally treated as a one line short title/description for the user. This value does not have to be unique, but it is best if your records have unique titles. This title is frequently used in drop-down lists and other GUI elements.

Some objects have a longer description, but this is not as common. The 'description' field is used for multi-line descriptions that are used in only a few places such as Product.

Each domain object will decide which status(es) it will use. The most important objects and statuses used are:

Most domain classes in SimpleMES can be extended with a limited number of custom fields. These are marked with the @ExtensibleFieldHolder annotation in the Groovy API documents. See the Field Extension documentation in the Enterprise Framework allows you to add new fields. Most SimpleMES definition GUIs allow you to edit these custom fields:

The relationship between Orders and LSNs is shown below.

LSNs are children of Orders. They are optional and do not need to be created in all cases. See LSN Tracking Option and LSN Creation Options for details.

Because this LSN has a combination primary key of order + lsn, the API calls using JSON need to be a little more complex. For example:

Then you can reference an LSN in a JSON request as:

If the lsn (SN2001 above) is unique, then you can leave off the order element. If the LSN is not unique, then you may receive an error if you attempt to process the LSN (e.g. Start).

This is a little awkward, but it gives you the ability to re-use the LSN in other orders. This might be useful for RMA processing or returned products. It might also be useful when you have no control over the serial numbers you need to use (e.g. your custom provides the serial numbers).

LSNs may be globally unique or can be unique within a given product or order. SimpleMES will attempt to find the appropriate LSN. This done by the fixLSN() method.

Tracking within SimpleMES is performed at the order level or at the LSN level. You must decide how LSNs will be used in producing the orders in SimpleMES. For a given Product, you have these options:

The options for tracking these LSNs are defined at the product level, but are copied to the order upon creation. This prevents problems when the tracking option changes later. The tracking option at the order level is the one used during production.

Some production actions can prevent processing by the entire order. This can be used to force use of LSNs in many scenarios.

LSNs may be assigned at order creation time or later as needed. This is configured by assigning an LSN Sequence to the product. See Product for details on how this is configured at the product level. LSNs are only automatically assigned on release when the product’s LSN Tracking Option is set to LSN Only. You can create the LSN yourself using the GUI or API for the other scenarios.

The automatic creation of LSNs is done by SimpleMES during the order release process. See OrderService for details. This only happens when the Order’s effective LSN Tracking Option is set to LSN_ONLY.

Depending on the Product’s LSN Tracking Option, individual pieces can be tracked by a unique LSN or as part of a larger lot. These flexible options mean that the quantity to be worked can be tracked at the order level or at the LSN level. This means the quantity is stored in multiple places in SimpleMES. The possible quantity tracking options are shown below:

If the routing exists for the product/order, then the quantities are tracked at a routing operation level. Each operation has the qtyInQueue, qtyInWork, etc. The basic relationship of the objects when routings are used are shown below:

If LSN Tracking Option is LSN Allowed or LSN Only, then LSN records will exist for the order. The quantity is then tracked at the LSN level. If LSN Tracking Option is Order Only, then the quantities are tracked at the Order level.

Upon order release, the Order copy of the operations are created. These are copied from the effective routing from the Product or MasterRouting. It is also possible to import an order with its own operations if needed.

The detailed operation states are stored in various places, depending on how work is tracked. All of these places implement the WorkStateTrait . This Trait provides most of the logic and persistent fields needed to track the state. It provides common methods such as queueQty() or startQty().

The various places this state is stored are:

By default, these records are automatically archived after 6 months. You can alter these settings by changing the Background Task for the production log archiver. This task has these options:

The archive JSON files are created using the ProductionLog.toShortString() method to form the file name. This contains the date/time of the first production log record in the archive. For example:

There is no ordering within the archive files, so it is possible for records from other date/times to be stored in the file.

Domain objects are used to store/retrieve properties of the SimpleMES objects. The domain objects are responsible for persistence and ensuring data integrity. This includes basic validations, but does not include cross-object validation except in the cases of child objects.

Services orchestrate various domain objects and other services to provide higher level services. In general, you should not directly use the domain objects in place of the appropriate service. For example, if you wish to start a quantity on an order, you should not use the Order object to adjust the quantity directly. You should use the WorkService to perform the start work action. This ensures proper logging, security and validation with all of the appropriate objects.

You can use domain objects directly in a few cases. In most cases, reading values is acceptable. Some direct updates make sense, but do not use direct updates to avoid the business logic in the services. Some domain methods are exposed in the service layer. We recommend that you use the service layer method when possible.

Most services take one or more POGOs (Plain of Groovy Objects) as input arguments. These POGOs are simple containers that hold values used by the service. A good example is the start() method:

This StartRequest POGO provides the fields needed to perform the start. Some fields are simple values (e.g. qty) and others are domain objects themselves. You will use Groovy/GORM features to populate these values.

A short example to start work on an order is shown below:

This example uses the WorkService, which is injected by Micronaut with the annotation. This code then finds the order using its key value ('M0001') and sets the quantity to start to 1.0. It then calls the service. The WorkService in this case moves the quantity to in work and logs a record to the ActionLog.

If the service fails, then it will throw an exception and the transaction will be rolled back.

Services follow the normal framework transaction logic. See Enterprise Framework for details.

The release() method is used to release an order to the shop floor for processing. The entire order or a portion of the order can be released. Automatic LSN generation, if needed, occurs at release time. See LSN (Lot/Serial Number) for details on when LSNs are automatically generated.

This method is exposed via HTTP in the /order/release URI. See OrderController .

Archiving is used to move an order to an JSON file to reduce the amount of data in the database. This will archive a single order and all of its children and history records at a time.

The archiveOld() method is used to archive old, done orders based on the date that they were completed. There are options for the age (days) and the max number of orders to archive in one batch (transaction). There is also an option to limit the number batches archived at a time. This last option is used to limit the slowdown from archiving during 'catch-up' scenarios when archiving has not been run recently.

Many common scenarios involve trying to start work on orders with limited information. This happens frequently with automated machines on the shop floor. The machines can read a barcode as the product enters the machine, but the machine has no real knowledge of SimpleMES data or what the barcode really means. It could be an order or an LSN.

To help with these cases, the Resolve service gives you methods to find the right records in SimpleMES to process. In most cases, the caller uses the Resolve service to determine the records for you. There may be times when you need to use this resolving logic yourself. The Resolve service can be used to 'fill in' the missing data in many of the services requests.

For example, the WorkService.start() method uses a StartRequest . The resolveProductionRequest() method will automatically fill in any missing information. You do not need to call the resolveProductionRequest() yourself in most cases.

The supported scenarios are:

In all of these scenarios, the operation sequence and work center can be provided too. If not provided, the service will attempt to find the right operation to process (if any). In some cases, the work center may also help narrow down the list of possible choices.

*TBD: Add notes on missing data exceptions *

See the MissingDataException in the Enterprise Framework documentation.

The resolveProductionRequest() method is used to fill in any missing information in most production requests. It will use the information already in the request and narrow down to a specific object to process.

For example, order M001 has a routing with 3 operations: 1,2,3. A start() request with only the barcode='M001' can be used to start the order at the current operation. This means the resolveProductionRequest) will find the proper order and the operation with a quantity in queue.

This method operates on production request POGOs that have the following fields:

All of these fields are individually optional, but you must provide enough information for the action to be performed. In some cases, a barcode alone will be enough to handle the action. There is also an option on this resolveProductionRequest) method to indicate if preference should be given to entities with a quantity in queue or quantity in work. For example, the start() method prefers to operate on quantities in queue.

The service will attempt to fill in the missing information using the following rules to fill in the missing information:

The resolveWorkable() to find the right level to process a given order and/or LSN. This is based on the Product settings and the current state of this order. This finds where the in work, in queue and other quantities are handled for these cases.

This method operates on a ResolveWorkableRequest POGO that have the following fields:

All of these fields are individually optional, but you must provide enough information to find the workable unit (LSN or order).

This fixLSN() method is used to make sure the given object’s order and LSN are consistent. A common use is when receiving a request POGO with the LSN and optional order. This looks something like this:

You will then de-serialize the given JSON:

The normal JSON de-serialization (using the framework @JSONByKey) will find the first LSN that matches 'SN2001'. This works great until you have duplicate serial number for another order. The de-serialization might find the wrong LSN.

To handle this, we have the fixLSN() method:

This method takes anu object with order and lsn fields that are domain object references. This method will throw an exception if the order/lsn combination is nor correct and the right LSN can’t be found.

This is the primary method in this services. It finds work that is in queue or in work with various filter criteria. This method returns a list of Orders/LSNs that match the criteria. The list is row-limited with the normal offset and max settings. This response also includes the total number of rows available, for support of paging.

This method performs 4 queries to find all types of work needed:

Most customers will use one of these combinations, but the MES will not limit you to just one. This means all four queries will be executed and combined.

Most of the production work service methods use a similar format for the request POGOs:

All of these fields are individually optional, but you must provided enough information for the action to be performed. In some cases, a barcode alone will be enough to handle the action. The Work service will attempt to fill in the missing information using the ResolveService. You normally don’t need to use the Resolve Service directly, but it is available for your use. The guide will give you some idea of the logic used to resolve to specific values in most requests.

The actual data required to perform the action depends on the configuration of your data. If you have no routings, then an operationSequence is not needed. If you do not use LSNs, then no LSN is needed. In many cases, SimpleMES can guess what you wish operate on, even if you do not provide all of the information.

A typical scenario is that you have a semi-unique barcode string to start work on, but you do not have the specific LSN, order or operation sequence to process. SimpleMES uses the ResolveService to narrow this down to a specific Workable object to process. In the case of multiple operations on a routing, SimpleMES will try to use the operation where the quantity is in queue for a start() action.

Most Work Service methods will automatically call the ResolveService.resolveProductionRequest() method at the start of the action. This will fill in the missing fields in the request.

Some of the key business logic for these Work Service methods is implemented in the WorkStateTrait . This includes the manipulation of the qty’s and dates in the workable object.

The Start method is used to begin work on an order or LSN. This can be the entire order, one LSN or just a portion. The work is performed at an optional work center and is logged to the action log.

The StartRequest object is the main argument for the start(). This is a simple POGO that you must populate before you perform the start. This method returns the order/LSN that was started.

The start() finds the appropriate Workable that matches the start request’s inputs (e.g. an Order or sub-element that can be started). The Work service then calls the startQty() on that Workable. This then validates that the Qty can be started.

If everything passes the validation, then the WorkService will log the start via the ActionLog. There is a corresponding reverseStart() method to "un-start" the work.

The complete() method is used to finish work on an order or LSN. This can be the entire order, one LSN or just a portion. The work is performed at an optional work center and is logged to the action log and ProductionLog.

This method returns the order/LSN that was completed.

The complete() finds the appropriate Workable that matches the request’s inputs (e.g. an Order or sub-element that can be completed). The Work service then calls the completeQty() on that Workable. This then validates that the Qty can be completed.

If everything passes the validation, then the WorkService will log the start via the ActionLog.

The MES core logic will start the Order/LSN if it is in queue. This start can be reversed with the normal dashboard Undo feature.

The Scan Dashboard is designed to work with optional modules. These optional modules can change the default flow and add more options to the dashboard behavior. To make this work, the scan dashboard and related objects work together to handle scans and update the dashboard as needed. The basic flow of a scan (Order scan) is shown below:

The scan request is sent to the server, which determines what the scan is and what to do with it. In this case, it is an order that is in queue and the server starts the order. After the start, a response is returned to the client that tells the dashboard to update the UI for the started order.

The default core logic attempts to resolve inputs using the following precedence:

The optional Modules can add objects to this list before or after the core objects.

To handle additional objects, the module should define a post method extension on the ScanService.scan() method as shown above. The Assembly module adds components to the search list (after the core objects). The extension looks for components to be assembled. It can then open an activity to collect other barcode inputs for the assembly data needed for that component.

The core dashboard logic will handle LSN and order scanning. Once resolved, the scanned order/LSN will become the 'current' order/LSN. This will be passed with the scan request so that the module can use this to help narrow down the choices for the scanned item. This helps find components required for a given order.

Barcode formats come in many shapes and sizes. SimpleMES does not require any specific format or scanner. The main requirements are:

Additional barcode format details are supported including:

The scan service will use any formatted barcode values to determine the type of object scanned. If no formatting is used, then the intelligent search logic will find the right object that matches the scanned value. The precedence in the core MES module is:

The optional Modules can add objects to this list before or after the core objects. For example, the Assembly module adds component to the search list (after the core objects).

For every scan, there is a ScanResponseInterfaces returned. This response contains a list of ScanActions that indicate what should be performed on the client.

These actions are POGOs that must contain a type, which indicates what the event is or action is. It is up to the client to determine how to process them. Each scan action will be sent to all dashboard activities as Dashboard Events.

See Scan Actions for specific details on the actions.