Installing Fiedler Data Explorer

This guide installs Fiedler Data Explorer on the OpenShift cluster that runs your IBM Maximo Application Suite (MAS). At the end, people open the explorer in a narrow window beside Manage, sign in through MAS, and walk through the data of Manage with their own rights.

Everything comes from two places. The container image is public on quay.io. Every script and every file of the installation is in one install kit, which you download from this page. The steps are the ones we run on our own test system, on the MAS 9.2 series.

Two people usually share the work. The OpenShift administrator deploys the app, sections 1 to 7. The Maximo administrator installs the Manage-side components and gives people access, sections 8 to 11. Fiedler Data Explorer belongs to Fiedler Data Tools and shares their licence with Fiedler Data Import and Fiedler Data Export. It runs on its own, and the order of the apps makes no difference.

What gets installed

#

In the MAS core namespace:

• One pod, with a data volume of 5 GiB. The volume holds each user’s search index and the boards of the Workbench. The pod runs beside IBM’s own MAS components and signs people in through MAS.
• A Route under the suite’s domain. Under subdomain routing it is the host fiedler-data-explorer.<domain>. Under path routing it is the path /fiedler-data-explorer.
• The app’s own service account, with a Role that may read and write one Secret, fiedler-data-tools-license, and read MAS’s Suite for its domain.
• A ConfigMap with two files: config.yaml with the settings, and navigation.json, the navigation document. Section 10 explains the document.
• Optionally, monitoring: a ServiceMonitor and a PrometheusRule with six alerts.

The licence Secret fiedler-data-tools-license is shared by the apps of Fiedler Data Tools. The first deploy of any of them creates it empty. Without a licence, the free edition applies, and Fiedler Data Explorer has no limits in its free edition for now.

In Manage, installed by the administration screen with the administrator’s own credential:

• Three automation scripts: FDEXPL_PING, FDEXPL_META and FDEXPL_INSTALL. They read Manage’s metadata, its saved queries and its action menus, and they install the Manage side. None of them writes to an asset, a work order or any other record of your business data.
• One application, FDEXPLORE, with its signature options, and two security groups.

1. What you need

#

2. The image

#

The app is one container image. It holds the server, the web interface with its fonts, and the app’s Manage-side scripts. The code in the image is obfuscated. The app needs no internet access at run time: it talks to MAS and Manage inside your cluster, and the browser loads nothing from another site.

Each version has its own tag, and latest follows the newest version. Pull the image without a login. Refer to it by its digest: a digest names exactly one build, and it stays the same in a mirror. This prints the digest of a version:

skopeo inspect --format '{{.Digest}}' docker://quay.io/fiedler-it/fiedler-data-explorer:1.0.0

The digest of version 1.0.0, also in the kit’s README.md:

Check the signature before you deploy a digest. The image is signed with cosign, and it carries its SBOM as a CycloneDX attestation. The key is the same one that signs Fiedler Data Import and Fiedler Data Export. Save the public key as cosign.pub, or take it from the kit:

-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEZDj9ekJEsZLiYU2DPfNHChqMi9xA
gB85czl1f+IhMVNaf3pLdiOyw0YDMQaXy+H0o1Nnfgm2QqYFsO9o8kZTpQ==
-----END PUBLIC KEY-----

Then check the digest you deploy. cosign needs no login for quay.io:

cosign verify --key cosign.pub quay.io/fiedler-it/fiedler-data-explorer@sha256:<digest>
cosign verify-attestation --key cosign.pub --type cyclonedx quay.io/fiedler-it/fiedler-data-explorer@sha256:<digest>

Mirror the image when the cluster has no route to quay.io. skopeo copy --preserve-digests keeps the digest, and the second command shows the same digest from your mirror:

skopeo copy --preserve-digests docker://quay.io/fiedler-it/fiedler-data-explorer:1.0.0 docker://<your-mirror>/fiedler-data-explorer:1.0.0
skopeo inspect --format '{{.Digest}}' docker://<your-mirror>/fiedler-data-explorer:1.0.0

For a network that is fully disconnected, we send the image as an OCI archive on request.

3. The install kit

#

The kit holds every file of the installation. Download it, check it and extract it:

• fiedler-data-explorer-install-1.0.0.tar.gz, the kit of version 1.0.0
• fiedler-data-explorer-install-1.0.0.tar.gz.sha256, its checksum

curl -LO https://fiedler.site/products/fiedler-data-explorer/installation/fiedler-data-explorer-install-1.0.0.tar.gz
curl -LO https://fiedler.site/products/fiedler-data-explorer/installation/fiedler-data-explorer-install-1.0.0.tar.gz.sha256
shasum -a 256 -c fiedler-data-explorer-install-1.0.0.tar.gz.sha256
tar -xzf fiedler-data-explorer-install-1.0.0.tar.gz
cd fiedler-data-explorer-install-1.0.0
shasum -a 256 -c SHA256SUMS --quiet

On Linux, sha256sum -c does the same as shasum -a 256 -c. All further commands run in the kit’s folder.

4. Find your cluster’s values

#

The overlay needs a few facts about your MAS installation. Each row gives the command that finds the value.

An empty routing mode means subdomain routing. A Manage split into several server bundles has one service per bundle, and the app uses the one marked as the default. The issuer must show Ready, and the right to create the Role must answer yes.

5. Write the overlay

#

The manifests are kustomize files. The base/ folder holds the app’s objects for any cluster, and an overlay adds the values of one cluster. The kit brings two example overlays: example-subdomain and example-path. Copy the one for your routing mode, and name the copy after your cluster. This uses prod:

cp -r deploy/overlays/example-subdomain deploy/overlays/prod

Every cluster value in it is a placeholder from the table of section 4. One sed fills them all. Put your own values in place of the examples here:

sed -i.bak \
  -e 's/<core-ns>/mas-prod-core/g' \
  -e 's/<instance>/prod/g' \
  -e 's/<domain>/mas.example.com/g' \
  -e 's/<workspace>/main/g' \
  -e 's/<bundle>/all/g' \
  deploy/overlays/prod/*.yaml
rm deploy/overlays/prod/*.bak

What the files of the overlay hold:

• kustomization.yaml: the namespace, the image name, and the optional components. Remove the # before components: and ../../components/monitoring when user workload monitoring is on. When you use a mirror, set the image’s newName to it.
• certificate.yaml: the app’s internal certificate, with your namespace in its DNS names and your issuer.
• deployment.yaml: a JSON patch with the app’s addresses: the routing mode, the domain, the MAS sign-in endpoints and Manage’s addresses. Each value comes after a test of the variable’s name, so a changed base stops the build before a value lands in the wrong variable.
• config.yaml: the app’s settings. A production system needs the one line Instance.Kind: production. The table below lists the others, and the defaults suit a first install.
• navigation.json: the navigation document, a starting point over IBM’s standard object structures. Section 10 explains it.

MANAGE_INTERNAL_URL in deployment.yaml points the app at Manage’s service inside the cluster, which is faster than Manage’s public route. Empty, the app calls Manage through its public route.

Check the overlay before you apply it. It must render, and no placeholder and no set-by-overlay may be left:

oc kustomize deploy/overlays/prod | grep -c -e set-by-overlay -e '<[a-z-]*>'   # prints 0

6. Deploy

#

deploy/deploy.sh does the first deploy in one run. It reads the namespace, the host and the path from your overlay, so the Route and the pod always agree. Pin the image by its digest:

DIGEST=$(skopeo inspect --format '{{.Digest}}' docker://quay.io/fiedler-it/fiedler-data-explorer:1.0.0)
OVERLAY=prod IMAGE=quay.io/fiedler-it/fiedler-data-explorer:1.0.0 IMAGE_DIGEST=$DIGEST ./deploy/deploy.sh

The script runs these steps and prints each one:

1. It checks your login and the issuer.
2. It creates the OIDC client secret with a generated value. The value lands in the cluster Secret only.
3. It creates the pull secret. An image from quay.io needs no login, so the pull secret holds no credentials. Then it creates the app’s service account with its Role and RoleBinding, and the empty licence Secret when that is missing. A licence installed later is never reset by a deploy.
4. It applies the overlay: the Certificate, the PVC, the ConfigMap, the NetworkPolicy, the Deployment, the Service, and the monitoring objects when the overlay has them.
5. It waits for the certificate, then creates the Route with the issued CA.
6. It registers the OIDC client with MAS through a short Job in the cluster.
7. It waits for the rollout and checks the result.

A good run ends with internalapi HTTP 200 and DONE: open https://<host><path>/ and sign in. The last step prints the app’s version through the Route, the sign-in redirect to MAS, the readiness answer, and a call from the pod to MAS’s internal API over mutual TLS.

From a mirror with a login, give the script the credentials once. It reads them only when the pull secret does not exist yet, and the password goes in without an echo:

export REGISTRY_USER=<user>
read -rs REGISTRY_PASSWORD; export REGISTRY_PASSWORD
OVERLAY=prod IMAGE=<your-mirror>/fiedler-data-explorer:1.0.0 IMAGE_DIGEST=$DIGEST ./deploy/deploy.sh

When Fiedler Data Import runs in the same namespace, the script can copy its pull secret instead, so no password passes through your shell: add REGISTRY_PULL_FROM=fiedler-data-import-registry-pull.

7. Monitoring, optional

#

With user workload monitoring on and ../../components/monitoring in the overlay, the deploy creates a ServiceMonitor and a PrometheusRule with six alerts:

Each alert carries a severity label, so your Alertmanager routes it. Check that Prometheus scrapes the pod: in the OpenShift console, under Observe and Metrics, the query up{job="fiedler-data-explorer"} gives 1.

The app also brings a Grafana dashboard, components/monitoring/dashboard.json, with the datasource as a variable. For a Grafana that the MAS CLI’s Grafana operator runs, add ../../components/grafana to the overlay’s components. It creates a GrafanaDashboard that this operator selects. A Grafana of your own imports dashboard.json and needs read access to the cluster’s metrics.

8. Accept the licence agreement and install the Manage-side components

#

Open the administration screen as the Maximo administrator:

Before the first install, the application FDEXPLORE does not exist in Manage, so nobody holds its options. The app therefore lets in a user who may save in the Automation Scripts and the Application Designer applications, and shows that user the components only.

The screen reads and writes the scripts through the object structure MXAPIAUTOSCRIPT, so that user needs its options too. On a Manage installed without demo data, even MAXADMIN lacks all three, and the screen says “No access”. Grant them to the group MAXADMIN in Security Groups: Automation Scripts and Application Designer on the Applications tab, MXAPIAUTOSCRIPT on the Object Structures tab. Then sign in again a minute or two later, when Manage has synchronised the profile.

First the licence agreement of Fiedler Data Tools. The screen shows it with Read and accept: read it, tick the box, and press Accept. The app records the acceptance with your user, the time and the version of the agreement. Install or upgrade stays off until then. The same text is LICENCE-AGREEMENT.md in the kit. An acceptance in another app of Fiedler Data Tools counts for that app only.

Then press Install or upgrade. The app does three things with your own credential:

1. Scripts. It creates or updates its three scripts through Manage’s standard object structure MXAPIAUTOSCRIPT.
2. Application, options and groups. Its install script creates the application FDEXPLORE, its signature options and two security groups. MAXADMIN and you join both groups.
3. Profiles. It clears Manage’s cached profiles of the groups’ members. MAS takes the new options at Manage’s next profile sync, often within two minutes. Then open the screen again, and it shows the rest of the administration.

The report lists every script with its result and the options you now hold. Pressing the button again is safe: an install that finds everything in place changes nothing.

9. Give people access

#

Add each person to the security group FDEXPLORE in Security Groups. The explorer shows a person what Manage lets that person read, and nothing more. It reads every record through an object structure, as the person who signed in. So each person needs two rights for every kind of record:

• The application. READ in the application the records belong to, such as Assets, Work Order Tracking, Locations, Preventive Maintenance, Job Plans and Routes. A relation into an application the person does not hold leaves no trace in the explorer.
• The object structure. READ on the structure the navigation document names for that kind of record, on the Object Structures tab of a group the person is in. The starting document uses MXAPIASSET, MXAPIWODETAIL, MXAPIOPERLOC, MXAPIPM, MXAPIJOBPLAN, MXAPIROUTES, MXAPIASSETMETER and, for the location systems, MXAPILOCSYSTEM.

A person who holds the application and lacks the structure sees the relation greyed, with the reason beside it. That tells the administrator which grant is missing.

10. The navigation document

#

navigation.json in the overlay decides what the explorer offers: the starting points, the kinds of record, and the relations between them. The starting document in the kit covers assets, work orders, locations, preventive maintenance, job plans, routes and meters. Adjust it to your data.

The document has four parts:

• types: each kind of record, with its object, the application that opens it, the object structure the app reads, the attributes it shows, and its relations. A relation reads related records by a where clause, a Maximo relationship, a path over several relationships, a location hierarchy, a saved query, or counts by an attribute. A relation with dates appears on the Timeline.
• roots: the starting points in the first column: an application with its saved queries, a query of your own, the location hierarchy, the user’s bookmarks, and the search.
• chains: saved paths, such as an asset’s open work orders and their tasks, which a user applies to a record from its menu.
• applications: which applications come first in the lists, and which ones the explorer never shows.

The app reads a changed document without a restart. Apply the overlay again, and about a minute later the pod has the new file. A document with a problem never replaces a good one: the administration screen names each problem with its place in the file, and the alert FdxNavigationRefused fires.

11. “Show in Explorer” in Manage

#

Manage can open the explorer on the record a user has open in an application. This uses Manage’s Launch in Context. The administration screen lists, under Show in Explorer, one URL per kind of record, and the target window fdx-explorer. For each kind of record you want:

1. In the Launch in Context application, create a launch entry with that URL and the target window fdx-explorer.
2. In the Application Designer, open the application, such as Work Order Tracking. Add a signature option that is associated with the launch entry, and put it in the application’s Select Action menu.
3. Grant the new option to the groups whose people use the explorer.

The explorer window then follows Manage with one click. A user can also paste the address of a Manage record into the explorer’s search field, drop it on the page, or read it from the clipboard with Alt+L.

12. Check the installation

#

Open the app as a person in the group FDEXPLORE:

The browser goes through the MAS sign-in and back. The Trail shows the roots of your navigation document. Open a root, a record and one of its relations. The user menu names the version, and the same version answers without a login:

curl -s https://<host><path>/api/version

On the administration screen, every script shows the expected version and the state “ok”.

13. Update

#

An update deploys the new image by its digest with the same overlay:

DIGEST=$(skopeo inspect --format '{{.Digest}}' docker://quay.io/fiedler-it/fiedler-data-explorer:<version>)
OVERLAY=prod IMAGE=quay.io/fiedler-it/fiedler-data-explorer:<version> IMAGE_DIGEST=$DIGEST ./deploy/deploy.sh

The data volume, the licence and the acceptance of the agreement stay. When a new version brings new automation scripts, the administration screen shows them as outdated, and Install or upgrade installs them. The release notes of each version name what changed.

The volume holds the boards of the Workbench and each user’s search index. The search indexes fill again as people work. To keep the boards safe, include the volume fiedler-data-explorer-data in the snapshots or backups of your cluster’s storage.

14. Remove the app

#

First the Manage side. On the administration screen, Uninstall shows what it removes: the three scripts, the application FDEXPLORE and its two groups. Type FDEXPLORE to confirm. Then the cluster side:

NS=<core-ns> ./deploy/undeploy.sh

The script removes the app’s OIDC client from MAS first, and then every object of the app. KEEP_DATA=1 keeps the data volume. The licence Secret stays, because the other apps of Fiedler Data Tools read it.

IBM and Maximo are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide.