Releases
3.1.0

3.1.0

Release notes for version 3.1.0 of the Rhize application.

Release date: 7 Mar 2025

⚠️
This release includes a breaking change to permissions, review the upgrade instructions for details.

Changes by service

The following sections document the changes this release brings to each service.

Admin

Add

  • Add REST Playground.
  • Add expand input JSON to BPMN editor Viewer mode.
  • Add includes properties of to material class.
  • Add SSO for Appsmith Portal.
  • Add pagination to Operations Event Definition sidebar.

Change

  • Change schema to accommodate inherited properties with custom resolver.
  • Change GraphQL Playground to use Apollo Sandbox.
  • Change to use libre-schema v3.1.0.
  • Change GraphQL types to match libre-schema v3.1.0.
  • Change scripts to force line endings LF for compatibility with Windows.
  • Change tree library with react-arborist.

Fix

  • Fix disabled Material Definition properties not showing as yellow.
  • Fix disabling inheritance of Material Definition Property that are inherited through classes.
  • Fix disabling property edits on approved entities.
  • Fix duplicate personnel class draft being created on start.
  • Fix equipment save not working under all scenarios.
  • Fix Operations Event Class search bar not showing results.
  • Fix sidebar menu to hide disabled not showing for all entities.
  • Fix work calendar entry not showing after being created and requiring refresh.
  • Fix lazy loading of MaterialDefinition, MaterialClass and WorkMaster when none exist.
  • Fix multiple HTML5 backend errors by adding DndManager to ArboristTree usage.
  • Fix incorrect error toast when Equipment Class Rule expression results in false.
  • Fix issue where certain errors would post to console and not show in Response field.
  • Fix REST Playground request headers and body not being both sent in POST and PUT requests.
  • Fix issue causing newly created Equipment to appear at bottom of list.

BPMN engine

Add

  • Add config logging to the terminal on start-up.
  • Add config validation checks, specifically nil checks and URL formatting+response checks.
  • Add generation of config file when prompted with flag and file path in terminal start-up.
  • Add obfuscation for sensitive information in config on publish.
  • Add JSONata expression evaluation query handler, for calling BPMN service tasks outside of a process.
  • Add synchronous message wait to allow BPMN to block execution and wait for a message.
  • Add span end to Call Activity error log.
  • Add dot support to MQTT topics
  • Add responseHeaders to RestAPI service task output variables
  • Add check for jobState in getInstance.
  • Add detection for when NATS deletes KV stores and to resync them.
  • Add domain object bpmn.Task for BPMN tasks that uses a domain.JobResponse as base type.
  • Add domain object for BPMN tasks.
  • Add EffectiveEnd to WorkCalendarEntry.
  • Add EvaluateJsonata domain function.
  • Add facades for service tasks with NATS Adapter & service tasks with Database Query Adapter.
  • Add gotemplate wrapper for ExpandEnvAndSecrets.
  • Add interface for service tasks.
  • Add internal variable to ExpandEnvAndSecrets for GraphQL URL.
  • Add TaskDefinition type to domain.

Change

  • Change to use YAML instead of JSON for configuration.
  • Change HandleCallActivity to use getWorkflowSpecification helper function.
  • Change go version from 1.22 to 1.23.
  • Change “ABORTED” Job State check in getInstance to reference jobState.
  • Change “ABORTED” Job State check in getInstance to be in final workflow span check.
  • Change configManager to accept a config file name argument.
  • Change domain.JobResponse functions to bpmn.Task functions.
  • Change Get/Set TaskVariable to be jobResponse domain functions.
  • Change individual service task functions to individual files and modified to adhere to interfaces.
  • Change job *domain.JobResponse to task *bpmn.Task & update symbol in functions.
  • Change JSONata compile and evaluation to be in a separate function.
  • Change pickServiceTaskDefinition to domain function on bpmn.Task GetServiceTaskDefinition.
  • Change pipelines to use CI_JOB_TOKEN in place of personal access tokens.
  • Change pipelines to use go version 1.23 and docker 27.4.1.
  • Change TaskDefinitions in domain to use base TaskDefinition type, for stricter type checking.
  • Change to check and log if workflowSpec is empty in HandleTaskAborted.
  • Change to importing libre-schema for types.
  • Change to separate ‘.’ and ’ ’ cases in MQTTToNATSSubjectConversion, adding new conversion for ‘.’ case to ‘//’.
  • Change to use globally configured CA for all GraphQL and REST requests.
  • Change WorkCalendar trigger to filter for only active equipment.
  • Change BPMN IntermediateThrowEvent to allow unconfigured IntermediateThrowEvents to complete successfully.

Fix

  • Fix BPMN SQL Task errors causing nil pointer exception for nil job.
  • Fix nil dereferences in bpmnEngine.go.
  • Fix getInstance not returning an endTime for a running BPMN.
  • Fix issue that would cause Task DataJSON to grow exponentially.
  • Fix issue where oidc.bypass was not being handled.
  • Fix issue with some NATS Connect instances not referencing username and password.
  • Fix WorkCalendarDefinition label field not aligning.
  • Fix Tempo search query parameter encoding for Instance searching.

Remove

  • Remove impossible error condition handling.
  • Remove repeated Call Activity error logging.
  • Remove unused config fields from configuration.
  • Remove OTEL URL validation.

Schema

Add

  • Add deprecation warning to incorrect JobOrder dispatch status’
  • Add deprecation warning to quantityUnitOfMeasure on MaterialLot, MaterialSubLot, PersonnelCapabilityProperty, MaterialCapabilityProperty, EquipmentCapabilityProperty and PhysicalAssetCapabilityProperty
  • Add migration directive for OperationsEventDefinitionVersion.workMasters
  • Add missing JobOrder dispatch status’ from the standard ISA-95 2019 standard
  • Add Operations Capability schema model
  • Add quantityUoM attribute to MaterialLot, MaterialSubLot, PersonnelCapabilityProperty, MaterialCapabilityProperty, EquipmentCapabilityProperty and PhysicalAssetCapabilityProperty
  • Add regex search to event message text
  • Add signature to InformationObjectTypeEnum
  • Add a alternative permission group for just Materials (MaterialLot & MaterialSublot) and their properties
  • Add continuous deployment for tagged versions to staging environments
  • Add continuous deployment for v3.x.x branch to Libre 3 (L3) staging environment
  • Add relationship between Workflow Specification Nodes and Work Master
  • Add migration directives for Work Calendar information model

Change

  • Change _createdDateTime to _createdOn for consistency
  • Change federation version from 2.7.0 to 2.9.0
  • Change migration method to parent for Hierarchy Scope’s inverse relationships
  • Change Operations Event Definition Record Specification ID to be unique (@id)
  • Change scripts to use docker compose instead of docker-compose
  • Change unicode characters to ascii
  • Change libre baas version from v3.0.1 to v3.0.3 in container builds and CI/CD
  • Change golang version to 1.23 from 1.21
  • Change build containers to use v3.1.0 of BAAS
  • Change comment signoff to allow 0..n, was 0..1

Fix

  • Fix circular dependency on migration of Hierarchy Scope
  • Fix ImportJSON mutation not checking for conflicts in data for versioned entities
  • Fix isAssembledFrom migration for MaterialClass
  • Fix migration to include equipmentVersions in HierarchyScope migration
  • Fix order of operations so both models are complete when generating entities and schemas
  • Fix diff check on commit
  • Fix incorrect merge that duplicated JobOrder Dispatch Status CANCELLED
  • Fix permission file format for Row Level Access Control
  • Fix BAAS permission file generation to align with existing installation instructions

Remove

  • Remove fulltext search on _createdBy and _modifiedBy
  • Remove gqlparse library version pinning in CI/CD
  • Remove generation of scopemap update in CI/CD
  • Remove publish of tagged subgraph to Apollo
  • Remove repeated word in resource Specifications descriptions
  • Remove @deprecation from JobOrder dispatch status’ Cancelled

BAAS

Add

  • Add authorization error messages when authorization fails on GraphQL queries
  • Add arguments to lambda execution
  • Add check for claims in token for Row Level Access Control
  • Add cli flag --graphql runtime-url to configure to override the base url of the custom url handler
  • Add command line argument to synchronize roles with OIDC Server
  • Add support for _Any type in @custom queries and mutations
  • Add @constraint directive handling to limit field values
  • Add Apollo Sandbox user interface as default handler
  • Add GraphQL documentation
  • Add nullability checks when adding nested objects to only nested objects
  • Add tags and Continuous Delivery (CD) for docker repository

Change

  • Change Apache thrift library to v0.13.0 from v0.12.0
  • Change CI/CD docker version to bump 27.4.1 from 20.10.16
  • Change golang.org/x/crypto to v0.31.0 from v0.27.0
  • Change golang.org/x/sync to v0.8.0 v0.10.0 from
  • Change golang.org/x/sys to v0.25.0 v0.28.0 from
  • Change golang.org/x/text to v0.18.0 v0.21.0 from
  • ⚠️Breaking Change permissions file structure from map[string][]interface{} to a known structure for resource authorization rules
  • Change string indexed fields to limit size to 64000 characters to prevent key overflow
  • Change SyncOIDCGraphQLResource to respective new cil flag for syncRoles
  • Change golang version from v1.21 to v1.23
  • Change alpha’s Cross Origin Resource Sharing (CORS) policy to allow all
  • Change Change Data Capture (CDC) payload to include all entity attributes changes in the transaction as a single object, instead of individual attribute changes.
  • Change regex to backticks from double quotes to avoid double escaping slashes
  • Change the GraphQL parser to gqlgen’s from dgraph-io’s
  • Change to chi as default http multiplexer from http.ServeMux

Fix

  • Fix authorization rewriter handling not:{has:acl} as type handling of []interface{} instead of interface{}
  • Fix error with custom http error responses not propagating
  • Fix security issue CVE-2024-41110 by upgrading docker library to 27.3.1 from 1.13.1
  • Fix security issue with possible sql injection attack

Remove

  • Remove authorization check on mutation
  • Remove commented out code as our SCM provides this history already
  • Remove unused code or superfluous comparisons

Core

Add

  • Add check for migration directives in schema.sdl for checkMigrationDependencies
  • Add check to prevent infinite loop when disabling Equipment
  • Add deprecation warning for changes to existing configuration keys
  • Add data exporter and importer
  • Add equipmentActualRollup as a query and accompanying resolvers.
  • Add exportJSON as mutation
  • Add handler for equipmentActualRollup to JobResponse handlers.
  • Add migration event as PENDING before execution
  • Add override of data when existing data in target DB is invalid
  • Add support for exporting multiple objects
  • Add support for YAML configuration files
  • Add tests for migration functionalities
  • Add timestamp in import event id so the same JSON can be imported again
  • Add update to migration event to COMPLETE after execution
  • Add update to migration event to update effectiveEnd when execution finished
  • Add validation check before executing to migration plan strategy
  • Add support for separating NATS username and password from connection string

Change

  • Change configuration keys names (backward compatible with deprecation warning)
  • Change import to allow empty effectiveStart while importing
  • Change import to use effectiveStart if set from DB when import data is empty
  • Change GetJobResponse query adapter to also get child JobResponses and EquipmentActuals.
  • Change github.com/99designs/gqlgen to v0.17.54 from v0.17.47
  • Change golang to v1.23.4 from 1.21
  • Change golang.org/x/crypto to v0.31.0 from v0.30.0
  • Change golangci-lint to v1.60.2 from v1.54.0
  • Change migrated entity versions to be imported with status DRAFT
  • Change CI/CD docker container build path to registry.gitlab.com/libremfg/docker/core from registry.gitlab.com/libremfg/libre-core
  • Change CI/CD docker version from 20.10.16 to 27.4.1
  • Change libre-schema to v3.1.0 from v3.0.3
  • Change GraphQL resolution of equipmentActualRollup to exist on Job Response instead of top level query
  • Change log to write as soon as possible after receiving message from NATS

Fix

  • Fix data source update when migrating an active version over the top of a draft version
  • Fix includesPropertiesOf cloning
  • Fix migration of circular HierarchyScope
  • Fix JIRA testcase upload pipeline CI/CD step

Agent

Add

  • Add adapter for MQTT v3.1.1.
  • Add field in config to choose MQTT Version.
  • Add field in config to choose timestamp field for JSON messages.
  • Add MaxMixedUpdates, allowing agent to run for a configurable number of failed config checks without access to Keycloak or BAAS.
  • Add configuration validation checks.
  • Add configuration logging on startup.
  • Add generation of config file when prompted with flag and file path in terminal start-up.
  • Add obfuscation for sensitive config fields on publish.
  • Add support for MQTT and NATS bridge mode.
  • Add Kafka egress handler using CloudEvents structured mode.
  • Add an adapter for Kafka event streams that implements DataSourceConnector, DataSourceWriter and DataSourceSubscriber.
  • Add configuration field for specifying which field to use as timestamp field using MQTT.timestampField and it’s format with MQTT.timestampFormat.
  • Add NATS KV support for message deduplication to the MQTT adapters.

Change

  • Change OCUPA version to newer version to take advantage of bug fixes.
  • Change config to use YAML instead of JSON, and certain configuration variables.
  • Change egress to be abstracted behind an interface, add configuration to select egress, inject egress providers into messageHandler.
  • Change messageHandler to support sending a message to multiple egress sources.
  • Change to allow Agent to trigger OPCUA commands without NATS.
  • Change Kafka adapter to use SegmentIO instead of Confluent library.
  • Change NATS reporting topics to native NATS topics.
  • Change stats reporting topic to a native NATS topic.
  • Change to update topic properties for dataType and messageKeyDeterminedBy when polling BAAS.

Fix

  • Fix issue where Agent would panic if DataSourceTopic DataType is missing.
  • Fix issue where OidcPEP.GetAccessToken was calling jwt.ParseWithClaims, resulting in a failed parse even with a valid Keycloak token.
  • Fix issue where Agent would panic if its config didn’t have an active version.
  • Fixed bug where unable to unmarshal raw string messages received through MQTT.
  • Fix issue with BaaS configuration change not updating existing topics.

Remove

  • Remove unused configuration fields: RESTAPI, BUFFERS.DataChannelCapacity, and AZURE.
  • Remove an extra config file.

Audit

Add

  • Add Previous field to ValueChange type, allowing querying of Audit history with Influx.
  • Add an HTTP endpoint “/config” that returns the active configuration with passwords, tokens, and client_secrets redacted. Endpoint is disabled by default and can be enabled by setting CONFIGLISTEN to any value.
  • Add custom postgres container with pg-partman and jobmon to optionally allow automated partition management.
  • Add logging of configuration options.
  • Add obfuscation for sensitive config fields.
  • Add pg_partman defaults to postgres init.
  • Add publishing the configuration to NATS \_libre.audit..status subject.
  • Add test cases for configuration.
  • Add validation to existing configuration with ConfigManager.

Change

  • Change CDC payload to accept multiple events per message, by updating ValueChange adapter to output an array of ValueChanges.
  • Change configuration to use YAML instead of JSON.
  • Change drivers to use rhize-go v3.0.0-3.
  • Change env prefix from LIBRE_AUDIT to RHIZE_AUDIT.
  • Change existing configuration options for consistency: pg to postgres, pg.user to postgres.user, and other options changed to camel casing.
  • Change go to 1.23 from 1.21
  • Change queries to use parameterized versions to avoid injection attacks.
  • Change influxdb.token to be optional.
  • Change NATS URL configuration to be split between serverUrl, username, and password.
  • Change postgres container to have 1 month default partition size.
  • Change to use the DTO to Domain conversion to create individual objects for the delete and set operations for Event objects.
  • Change value change logging from Trace to Debug.

Fix

  • Fix libreAudit not accepting audience in access token, now accepts both audit and .
  • Fix bug preventing messages from being ACK/NAKed when the Audit record was written to Influx.
  • Fix handling for user tag in filter and output.
  • Fix error where commit_ts and uid in postgres init were integer instead of bigint.

Remove

  • Removed unused configuration options: libreDataStoreGraphQL, logging.type, OpenTelemetry, and influxdb.

Keycloak Theme

No changes for this release.

Router Initilazation

No changes for this release.

Compatibility

v3.1.0 compatibility Rhize v3.1.0 has been tested to work with the following third-party applications:
  • Apollo router 1.61.0
  • Grafana: 9.4.7
  • Keycloak: 21.1.2
  • Keycloak Postgres: 15.3.0
  • Loki: 2.9.12
  • NATS: 2.10.25
  • Tempo: 2.7.1

Checksums

When you install, check the container images against these checksums:

Admin:
registry.gitlab.com/libremfg/frontend/libre-admin-ui:v3.1.0
sha256:7e885915dd7d91e22172235187b90bbee0b72fcc89bbd964fab86819f05da930

BPMN Engine:
registry.gitlab.com/libremfg/bpmn-engine:v3.1.0
sha256:ca13da0d99aa8de4a16a7b1eee6b2d1e1c70a883797beda41a26e0df4453791b

BAAS:
registry.gitlab.com/libremfg/baas:v3.1.0
sha256:632226e86a8ca6175287ab2a597b6a31325118fb125daa499bcf4916cafb90f1

Libre Core:
registry.gitlab.com/libremfg/libre-core:v3.1.0
sha256:eae5c2cbebf0cbc84b4ce543beae8d474a794cb2138e512daf0d11c4b54b93bb

Libre Agent:
registry.gitlab.com/libremfg/libre-agent:v3.1.0
sha256:90d6cfce491002d2bf7cfb1042ca97cafc70c5b4987a6f9c79d143ef1b69dd3d

Libre Audit:
registry.gitlab.com/libremfg/libre-audit:v3.1.0
sha256:5e8d5a45d8d4b5a72382922a32f6b8574b6b70b26a0298964e75e1c40e84d4ec

Libre Audit Postgres:
registry.gitlab.com/libremfg/libre-audit/postgres:v3.1.0
sha256:81b22e9a15fca26778693e546fa772fa579b68a993b5eadec22103dacf96e56d

Libre Keycloak Theme:
registry.gitlab.com/libremfg/frontend/libre-keycloak-theme:v3.1.0
sha256:a622c02be76e62059162c0c380b61066e4600a646067c3d4046d8a3fb358b5f1

Libre Router Init:
registry.gitlab.com/libremfg/libre-router-init:v3.1.0
sha256:afaa3739d7753869bcf543467c096af9b7a53e4d648d180685027f0fc5210661

Download v3.1.0-checksums.txt

Upgrade

Back up first Before upgrading, consider backing up your Rhize services. To review the procedure, read our Back up guides.

To upgrade to v3.1.0 from v3.0.3, first ensure that you have made corrections for the following breaking changes.

Row Level Access Control

Rhize now features row level access control. It also requires a different scopemap than previous versions of BAAS. This is a breaking change.

The new scope map features rules and jurisdictions. Jurisdictions can be used to create a group of permissions for certain entities within a hierarchy scope. This is useful for allowing contract manufacturing organizations to read and write to the data hub without being able to access the entire manufacturing knowledge graph.

If you are updating to v3.1.0 from 3.0.3 or lower, update your BAAS scopemap to add a rule with the admin role.

Your scopemap should have the following rule in some form. Note that admin is case-sensitive:

{
    "id": "rule-001",
    "description": "Admins can do everything",
    "roles": [
        "admin"
    ],
    "resources": [
        "*"
    ],
    "actions": [
        "*"
    ],
    "jurisdictions": [
        "*"
    ]
}

Read how to Configure your scopemap.

YAML config files

Rhize services now use YAML instead of JSON for their configuration files. This is represented in Helm overrides by the object rhize<SERVICE>Config (i.e. rhizeAuditConfig). Charts for v3.1.0 should create only YAML config files, though there may be differences in the keys for certain configuration options. Consult the values file for each Helm chart and the changelog for specific changes as necessary.

Notable schema changes

Material Lot & Sublot Quantity Unit of Measure

  • quantityUnitOfMeasure has been deprecated in favor of quantityUoM for MaterialLot and MaterialSubLot in order to standardize variable names across the schema. While quantityUnitOfMeasure is deprecated, it will continue to work until it is removed in a future releaase. To migrate before the quantityUnitOfMeasure is completely removed, ensure all clients are now using quantityUoM:
  1. Query all quantityUnitOfMeasure for MaterialLot and MaterialSubLot, and store information to disk.
  2. Delete all relationships for quantityUnitOfMeasure from MaterialLot and MaterialSubLot.
  3. Upgrade schema.
  4. Patch in stored quantityUnitOfMeasure as quantityUoM for MaterialLot and MaterialSubLot.

Job Order Dispatch Status

  • DispatchStatus has been changed to match the ISA-95 standard. Existing statuses that didn’t align are now deprecated. They will continue to work until removed in a future release. It is recommended to migrate clients to the new set.

Operations Event Definition Record Specification Uniqueness

  • The id field for OperationsEventDefinitionRecordSpecification has been changed to use the @id directive. Each id must now be unique, thereby any duplicate ids will cause issues. To fix:

    1. Query all id on OperationsEventDefinitionRecordSpecification, and store information to disk.
    2. Determine any duplicate values.
    3. For any duplicate values, assign a unique id.
    4. Patch in any id changes.
    5. Upgrade schema.

WorkMaster defines & definedBy

  • WorkMaster has been changed to invert defines and definedBy, such that defines is now a list and definedBy is now scalar. Depending on what version you are upgrading from you may come across this error when upgrading:

    {"errors":[{"message":"input: rpc error: code = Unknown desc = succeeded in saving GraphQL schema but failed to alter Dgraph schema - GraphQL layer may exhibit unexpected behaviour, reapplying the old GraphQL schema may prevent any issues: Type can't be changed from list to scalar for attr: [WorkMaster.definedBy] without dropping it first.\ninput:3: resolving updateGQLSchema failed\n","extensions":{"code":"Error"}}]}

    To fix:

    1. Query all id for definedBy and defines on WorkMaster, and store information to disk.
    2. Determine any relationship changes.
    3. Acquire a token with BAAS’s credentials from Keycloak.
    4. Drop definedBy attribute with this command:
    curl -X POST <BAAS_URL>/alter -d '{"drop_attr": "WorkMaster.definedBy"}' \
    -H "Authorization: Bearer <TOKEN>"
    1. Upgrade schema.
    2. Patch in any defines and definedBy relationships as needed.

After you’ve made the necessary mitigations, follow the Upgrade instructions.

3.0.3