Magic Software
Lesson 5Hands-on · ~45 min

Scan for New Requests

Now the analysis is done and the resources are ready. It's time to translate the business process into actual flows. In this lesson you'll meet the Flow Editor, build your first flow, and use the Directory Scanner and Email components.

The Flow Editor

The Magic xpi Studio has three primary panes:

  • Solution Explorer — lists projects, business processes, flows, repositories.
  • Toolbox — the flow components and triggers you can drop onto the canvas.
  • Main pane — the Flow Editor, where the actual flow is built.

The Flow Editor itself has two areas:

  • Trigger area — defines when and how a flow is invoked.
  • Flow area — the body of the flow, where you wire components together.
The full Studio showing toolbox, flow editor with trigger area, and the solution explorer
The Studio layout: Toolbox on the left, Flow Editor in the middle, Solution Explorer and Properties on the right.

Defining a flow

When you create a project, Magic xpi adds a default flow named Flow-1. You can rename it to suit the integration project.

Renaming flows

  1. In the Solution Explorer, select Flow-1.
  2. Right-click and choose Rename.
  3. Type Scan for New Requests and press Enter.

Creating a new flow

  1. Right-click the Business Process where the flow should live.
  2. Choose Add Flow. A new flow is created with the name Flow-N.
Solution Explorer with Business Process-1 expanded showing several flows and a new Flow-9 being renamed
The Solution Explorer with several flows in a Business Process. Right-click any flow to rename, duplicate, or delete it.

Flow properties

Each flow exposes a set of properties. To inspect them, select the flow, right-click, and choose Properties. The Properties pane groups properties under General, Enablement, and External.

Flow properties pane with General section visible showing Auto Repeat, Auto Start, Enable, etc.
The properties of a single flow.
Name / DescriptionIdentification and documentation.
Auto RepeatRe-runs the flow whenever the last step finishes — creates a loop.
Auto StartInvokes the flow when the project loads on the Server.
DB TransactionSelects which transactional resources participate in this flow.
EnableTurns the flow on or off at deployment time. Can be toggled at runtime via the Enable Flow utility.
ActiveExcludes the flow from the Checker and from deployment when set to No.
Max InstancesHard cap on simultaneous invocations — 0 means unlimited.
Recovery / Timeout PolicyBehavior on errors and on long-running steps.

Introducing context variables

When a flow runs, it often needs a temporary place to store information — to refer to it later, or pass it between flows. Magic xpi predefines context variables you can reuse, and you can define your own.

You'll use these predefined context variables in this lesson:

C.UserStringString, up to 1,000 characters.
C.UserCodeNumeric, up to 12 digits.
C.UserBlobBinary data.
C.UserXMLText data; commonly used for XML payloads.
What's a context? A context is created when a new flow is invoked. Context variables live as long as the context lives. They are defined once for the project and accessible in every flow. Lesson 6 covers variable scope in depth.

Flow components

Magic xpi ships an extensive component library — connectors, adapters, converters, and processors — surfaced in the Toolbox under headings for their category.

The Toolbox with Utilities and Triggers expanded showing components like Data Mapper, Email, Salesforce, REST API, etc.
The Toolbox in 4.14.1 includes modern triggers like REST API, Kafka, MQTT, and Azure Service Bus alongside the classic ones.

Directory Scanner component

The course business process drops requests into a directory on the server. A flow then watches that directory for new files and processes them. The Directory Scanner component is purpose-built for this: it checks LAN and FTP directories for matching files and can move, copy, delete, or rename them as part of the same step.

The Directory Scanner runs in two modes:

  • Step mode. Once per execution, with a configurable timeout. The step finishes when the first matching file is found or the timeout elapses.
  • Trigger mode. Fired by the Server — keeps scanning the directory while the project is running.
The Directory Scanner trigger as it appears in the trigger area
Step mode for now. You'll use the Directory Scanner in step mode in this exercise, but in production it's usually better to use it as a trigger so the flow reacts to new files immediately. You'll see triggers again in Lessons 11 and 12.

Placing the component

To use a component, drag it from the Toolbox onto the Flow Editor.

  1. Click the Directory Scanner component in the Toolbox under Triggers.
  2. Hold the left mouse button, drag onto the canvas, and release.
An empty flow editor with the toolbox open and Directory Scanner trigger highlighted
An empty flow ready to receive the Directory Scanner step.
Branch placement. If components already exist on the canvas, drop the new component on the step that should run before it. Magic xpi inserts the new step as the next link in the flow.

Component properties

Once placed, each component shows its properties in the Properties pane:

The Directory Scanner step properties pane with general, advanced, logging, and setting sections
Per-step properties for the Directory Scanner.
Step NameThe name shown on the canvas and in the logs.
Step ID / Component ID / TypeRead-only identifiers.
ConditionBoolean expression that decides whether the step runs.
Processing ModeLinear, Parallel, or Stand Alone.
Wait for CompletionWhether to wait for parallel siblings before continuing.
InterfaceXML (configured by an XML file) or Method (configured via the Direct Access Method dialog).
Logging Scope / Step Logging OptionsPer-step logging detail.
Resource NameSelects which resource provides connection details (only used for FTP modes).

For this exercise, set Step Name to Scan Directory and Interface to Method.

Configuring the Direct Access Method

Most components must be configured with their actual behavior. An unconfigured component shows a red wheel in the upper-right corner; double-click it (or right-click » Configuration) to open the configuration dialog. For the Directory Scanner you'll use the Direct Access Method:

  1. Click Add to add a method.
  2. Select LAN to LAN from the combo — this moves files between two local directories.
  3. Fill in the parameters listed below.
Direct Access Method dialog showing the LAN to LAN method with parameters like Source Directory Location, Filter, Destination, etc.
The Direct Access Method dialog. Bold parameters are mandatory.
Source Directory LocationEnvVal('currentprojectdir')&'course_data\in\'
Filter'request???.xml' — the ? wildcards match a single character.
Destination Directory LocationEnvVal('currentprojectdir')&'course_data\out\'
OrderAscending
CriteriaName
Return File ToC.UserXML — the file content is returned here.
Return Destination Filename ToC.UserString — the destination file name is returned here.
About EnvVal. EnvVal('currentprojectdir') resolves to the project's directory at runtime. You'll learn the full Expression Editor in the next lesson; for now, type the expression literally.

Exercise

Time to put it together — you'll add an Email step and prove the flow works end-to-end.

Email component

The Email component sends and receives email messages, including attachments. It can send/receive multiple messages at once and filter received mail by criteria. For this exercise you'll use the Quick Send method, which opens the connection, sends a single message, and closes the connection.

Add an Email step.
  1. Drop an Email step after the Scan Directory step. Name it Send Email to Sales. Use the Quick Send method.
  2. Use these field values:
    • To: your own address (so you can verify the test). Hard-coded for now — you'll switch to a global variable in Lesson 6.
    • Subject: A new request has arrived
    • Body: A new request has arrived.
    • Attachment: the original request file. Hint — look at C.UserString set by the Directory Scanner.

Test it

  1. Click the Scan Directory step and from the context menu choose Breakpoint (a red dot appears).
  2. Right-click the Scan for New Requests flow and choose Debug.
  3. Magic xpi runs the Checker first; fix any reported errors.
  4. In the Context Tree, click Scan Directory (n) and choose Step — repeat until both steps complete.
  5. Open the Debug xpi menu and choose Stop Debugging.
  6. Check your inbox for the test message.

Summary

You can now:

  • Add and rename flows in a Magic xpi project.
  • Configure flow properties.
  • Drop components onto the canvas and configure them.
  • Use the Directory Scanner and Email components.
  • Use the Debugger and breakpoints to walk through a flow.