MCP Sample and Verification Tools¶
These tools let a model work with a channel's sample messages and check a channel before anyone relies on it.
Sample messages¶
A channel save through save_object never adds, changes or removes a sample message. These four tools are the only way the MCP server does.
| Tool | Access | Does |
|---|---|---|
list_samples |
Read | Lists a channel's samples: each one's id, description, format, size and origin, and whether get_sample returns its body now. Bodies are never listed. |
get_sample |
Read | Returns one sample's body, in parts, under the rules in Sample Message Origin. |
push_sample |
Full | Adds a sample with a description, a format and a body, recorded as sent through the MCP server by the signed-in user. |
delete_sample |
Full | Deletes one sample, after the person confirms it in the MCP client. |
push_sample and delete_sample take the channel's revision token from get_object, so a channel changed in the meantime is refused as stale. Each saves the channel through the same checks as save_object, and returns the channel's new revision token.
A pushed sample goes after the channel's last sample. An HL7, XML, JSON, CSV, X12, EDIFACT, ASTM or plain text sample arrives as text. A binary, DICOM or ISO 8583 sample arrives as base64. A binary or ISO 8583 sample is stored as its bytes, and in an ISO 8583 channel an ISO 8583 body must read by the channel's field definitions. A DICOM body must read as DICOM, and is stored as its tags in JSON, the form the DICOM editor on the Sample Messages tab shows and the Test tab reads, so it can be viewed, edited and tested in the console like a sample made there. ISO 8583 samples need the ISO 8583 module. The whole request must fit the MCP server's request size limit, so a large file is added in the console. Add a fixed-length sample in the console.
get_sample returns a binary or ISO 8583 sample as base64, so it can be sent back unchanged, a DICOM sample as its tags in JSON (dicom_json), and any other sample as the console shows it. Its encoding says which.
delete_sample is confirmed because nothing brings the sample back: restore_revision keeps a channel's samples as they are now. See MCP Revision History Tools.
Warning
While Return message content is off, any user who can view the channel can read back a sample added through the MCP server. Push only samples that hold no patient data.
Test runs¶
A test run sends one of a channel's saved samples through the saved channel one node at a time, as the Test tab does, without sending anything from a destination. Every node before the destination runs for real, including a Web Service function's call and a Database function's query.
| Tool | Does |
|---|---|
test_step |
The first call runs the source node: the channel's before-start scheduled scripts, its preprocessor script when the channel uses one, and the parse. Each later call runs the next node. |
get_test_result |
Returns the result of a step that was still running when test_step returned, or the last step's result again. |
clear_test_session |
Ends the run, so another can start. |
Each step returns what the node did: the message after it, its log lines, whether a condition was met, and the script error if one stopped it. It also lists the nodes the message goes to next. Where a path splits, the next test_step must name one of them as next, as the Test tab asks which node to follow. A mapping that spawns new messages reports how many and lists them, and the run continues with the first of them, since a mapping that splits a message usually discards the original. The next test_step can send continueWith as another spawned message's messageId, or as original when the mapping kept the original, as the Select Next Message dialog offers on the Test tab. A discard after a split is not an error.
A run ends at a destination node, at the end of a path, or at a script error, as the Test tab stops there. When the next node is a destination, the step's result says so in a note: the next step ends the test, and a test writes no file and sends no message. It also ends with clear_test_session, or after 30 minutes unused.
A step that takes longer than 5 seconds returns before it finishes. Call get_test_result within a minute for its result: the engine stops a step that nobody has asked about for a minute.
Who can run a test, and why¶
A test run needs an access token approved for full access and edit rights in the channel's zone. The steps run the channel's scripts on the engine, with the same access to the server, its files and the network as a running channel, so a script can change things outside QIE during a test. Without this rule, a user approved only to read could run code through a test.
For the same reason, a run uses only what is saved. The model names a saved channel and a saved sample, and every step runs the node as it is saved now. To test a change, save it first.
Each access token has one run at a time. test_step refuses to start a second one while the first is still going.
What a run returns while message content is off¶
While Return message content is off, only a sample added through the MCP server can be tested, and a sample added in the console is refused. Each step then returns what it did, and nothing that can hold message data: which node ran, whether a condition passed, which node comes next, why the run ended, and the step's error with its message text dropped, as get_message_error drops it. The message after the step, the messages a split spawned and the step's log text are left out. The channel's scripts can put data into the message that the sample never had, such as a database lookup, a cache value or a web service response, so the output is withheld even for a sample the model sent itself.
While the switch is on, each step also returns the message, the spawned messages and the log text, and is recorded in the MCP audit log as a CONTENT_READ entry that names the channel, the sample and its origin.
Checks before saving¶
These checks read nothing QIE has stored, so they work whatever Return message content is set to.
| Tool | Checks |
|---|---|
validate_expression |
A cron string, listing its next 10 runs in the server's time zone; a date format, showing the time now in that format; or a Java regular expression, matched line by line against text the model sends, as the console's regular expression test matches it. |
validate_node_path |
A node path, read from a message the model sends, as the Validate button in the Node Lookup dialog reads it. It returns how many nodes match and up to 30 of their values. It reads HL7, X12, EDIFACT, XML, JSON, ASTM and plain text; for plain text, the path is a start and end position, such as 0,10. |
check_script_syntax |
A script, parsed as QIE's script engine parses it, without running it. Each syntax error comes with its line and column. |
A cron string joined with | runs at the earliest of its parts. A part that never runs, such as one for February 30, makes the whole string invalid, because QIE cannot schedule it.
A regular expression match stops after 2 seconds, or after 100 matches, so a pattern that backtracks for a long time cannot hold up the server. The text can be up to 100,000 characters.
check_script_syntax needs an access token approved for full access, as a test run does, because it takes a script.
Connection tests¶
test_connection tests a saved connection exactly as it is saved:
- A database connection, by its id.
- A channel's source: a file, FTP, SFTP or network share path, or a web service listener.
- A file or network share source's archive path (
channel_source_archive). A network share archive is tested with the archive's own Username and saved password. - A destination's file, FTP, SFTP or network share path, by the destination node's id.
It needs an access token approved for manage access and manage rights in the zone the connection or channel is saved in. The test runs with the saved settings and the saved password, which the engine reads for itself. To test a change, save it first. This is deliberate: the console's Test buttons take the host from the screen and fill in the saved password, and through the MCP that would let a model send a saved password to a host it chose.
A path test resolves the path's node tags and shows the result, and can create and delete a test file in the folder, as the console's Test button does. So a saved path that uses a password node tag, {v-pass:...} or {ws-pass:...}, with or without options such as [required], is never tested, and one that reads a channel or shared cache value is tested only while Return message content is on. A source path or archive path that uses a message cache node tag is refused, as the console refuses it. An FTP or SFTP archive path is tested in the console.