Magic Software
Lesson 8Concepts · ~20 min read

The Runtime Environment

Up to now you've been running everything inside the Debugger. This lesson looks behind the curtain at what actually executes a deployed project — the Magic xpi Server — and at the Magic Monitor dashboard you'll use to track its activity.

The Magic xpi Server

A Magic xpi project is a tree of business processes, flows, and steps. The Magic xpi Server is the background process that loads those instructions and executes the components in the order your flow logic dictates. There is no UI — the Server runs headless and reports to the Magic Monitor.

The Magic xpi installation gives you several cooperating pieces:

  • The Studio — for developing the project.
  • The Server — for running it.
  • The Magic Monitor — for observing it.
  • The GigaSpaces middleware (the Magic Space) — the in-memory grid used for messaging and shared state.

Building the Executable

In development, the Studio writes the project as XML files under <Documents>\Magic\projects\<Project name>\current project\Source. To deploy you need an executable file (extension .ibp):

  1. Open the Build menu.
  2. Choose Build Solution, or press Ctrl+Shift+B.
Build SolutionOptimized build — only modified objects are regenerated. Runs the Checker first; build is aborted if errors exist.
Rebuild SolutionRebuilds everything from scratch, ignoring optimization. Also runs the Checker.
Heads up. When you use Build Solution, the Checker does not flag unused variables. Use Rebuild Solution or run the Checker manually if you want a stricter pass.

Starting and Stopping a Project

The Server reads two environment variables to decide what to load:

currentprojectdirThe folder containing the project files.
currentprojectThe full path to the .ibp executable.

Both are predefined and updated by the Studio whenever you build. Building also updates the Windows Start menu shortcuts under Projects » <Project Name>:

  • Start — launches the Magic xpi Server (if not running) and loads the project.
  • Stop — tells the Server to stop processing the project.

How a Project Initializes

When a Magic xpi project starts, the Server runs through these steps:

  1. The Server is assigned a Server ID.
  2. It reads the environment variables and loads the executable file.
  3. If no other Server is hosting this project, it creates the project in the Magic Space.
  4. The Server is now ready to accept requests.

Each activity is logged in the messaging system and visible in the Magic Monitor's Activity Log. The Flow Manager is the Server subsystem that actually executes flows: it inspects each step's return code, runs the error handler if needed, decides which step is next, dispatches to remote Servers when steps live elsewhere, and manages transactions when transactional resources are involved.

The Magic Monitor

The Magic Monitor is a browser-based dashboard for tracking your project's health in near-real-time. It surfaces messages, flows, triggers, server details, locks, subscriptions, scheduler entries, the Activity Log, ODS, BAM, and a Summary view.

To open it:

  1. Right-click the Magic Monitor shortcut in the Start menu and choose Properties.
  2. Edit the URL to point at the host running the Monitor services — for example http://10.1.3.75:8068/magicmonitor/panels.jsp.
  3. Click the shortcut. Log in with admin / changeit.
Changing the port. The Monitor's web server defaults to port 8068. To change it, edit <install>\Runtime\RTView\servers\apache-tomcat-6.0.18-sl\conf\server.xml and update the Connector port.

The Projects Dashboard has two panes — a list of projects on the left (with Start/Stop/Restart controls) and a detailed view on the right showing messages, license usage, workers, alerts, and trigger activity.

The Activity Log

The Monitor's Activity Log tab is where you'll spend most of your debugging time once the project is running outside the Studio. Each row is one log entry from the Magic xpi Server.

Date & TimeTimestamp (millisecond resolution).
Message TypeServer-start/-end, flow-start/-end, component-start/-end, error messages (shown in red).
Message StringFree-text description of the action.
FSIDFlow Sequence ID; 0 for messages that don't belong to a specific flow.
BLOBHolds any BLOB attached to the entry — a request payload, an SQL error, etc.

Exercise

Run your project outside the Debugger.
  1. Save the project.
  2. Build the executable file.
  3. Open the Magic Monitor and log in.
  4. Start the Magic xpi Server for your project from the Start menu shortcut.
  5. Watch your project's activity in the Monitor as a request is processed.

Summary

You should now be able to:

  • Build executable files from the Magic xpi Studio.
  • Start and stop the Server for a specific project.
  • Open the Magic Monitor and navigate between its panes.
  • Use the Activity Log to follow what your project is doing in production.