Skip to content
SmartFACT HelpHandbooksWatch and practise
Handbooks: OrderRun

Connect your own software and look an order up

Connect the software your orders live in, look an order up by its reference and follow the events sent back.

Review edition · 16 November 2026 · For Owner, Supervisor

On this page

Use this guide when your orders live in your own software and you want OrderRun to read them from it. The Owner connects the software once, under Site, Your own software. After that a Supervisor can look an order up by its reference on Order intake, in place of uploading a file. OrderRun also tells your software when work is released and when its receipt is verified.

A lookup only prepares an order for review. A Supervisor still reviews and accepts it, and release still needs its approvals. A lookup never releases anything.

Status, 11 November 2026: OrderRun on SmartFACT's hosted service is not yet set to call out to your software. Until it is, an Owner can create the connection, save its addresses and generate its secrets, but a test lookup is refused before it leaves, so no version can be made live. No order can be looked up from your software and no event is sent to it. The page says so under This installation is not set to call out. No customer's software has yet been connected to OrderRun.

What your developer provides

Your developer builds two https addresses in your software, from OrderRun's customer endpoint contract:

  • a lookup address, which answers "give me the order with this reference";
  • a callback address, which receives events from OrderRun and acknowledges them.

OrderRun always calls your software. Your software never signs in to OrderRun. Every request is signed with a secret that OrderRun generates and you pass to your developer, so your software can check the request really comes from OrderRun.

Both must be public https addresses by name. OrderRun does not call an IP address, an internal name or an address with sign-in details in it, and it never follows a redirect.

Connect it

You need the Owner role at your real site. Each change on this page asks for your second factor again if the last one is more than five minutes old.

  1. Open Site, Your own software.
  2. Under Connect your own software, enter a Name and a Source ID, then select Create the connection. The source ID is a short label your software repeats in every answer. It cannot be changed later.
  3. Enter the Lookup address, the Callback address and the Source namespace, then select Save the addresses. The source namespace is the name of the set of order references your software owns. Orders read from it belong to that namespace, and only orders of that namespace are told to it.
  4. Select Generate the lookup secret. Copy the secret and its key ID and give them to your developer by a route you trust. Then select Generate the callback secret and do the same.

Each secret is shown once, on the page that follows. OrderRun keeps it encrypted and never shows it again. If one is lost, replace it: the earlier one stops working at once.

The page lists what is still to do under Before this connection can be made live.

Send a test lookup, then make it live

A version of the addresses cannot be made live until a test lookup of it has passed.

  1. Under Send a test lookup, enter an Order reference to ask for and select Send test lookup. Use a reference your software knows, so that a whole order is checked.
  2. Read the result. Test lookup passed means your software answered a signed request in the agreed form. If it did not pass, the sentence gives the reason and a short code for your developer. Where the installation is not set to call out, nothing is sent and the page says “Not done: this installation is not set to call out, so nothing was sent.”
  3. Select Make version 1 live.

A test lookup brings nothing into OrderRun: no order, no intake and no hold. It shows that the address answered correctly at that moment. It is not a check of your data.

If you replace the lookup secret after a test has passed, send the test lookup again once your developer has installed the new secret.

Look an order up

You need the Supervisor role. The lookup is on Order intake while a connection is live.

  1. Under Look an order up in your own software, enter the Order reference exactly as your software has it. Leading zeros, case and punctuation matter.
  2. Select Look up and prepare order.
  3. Review the exact source values that open, as you would for a file. The review is named Lookup of and the reference.
  4. Continue in Orders and amendments to accept the revision, as in prepare and accept an incoming source revision.

To read a changed order, look it up again. OrderRun records the new revision for you to review.

If Order intake says “This installation is not set to call out, so a lookup is refused before it leaves. Ask your Owner to check Site, Your own software.”, nothing can be looked up until sending is switched on for the installation.

When an order cannot be read

OrderRun guesses nothing. If your software does not answer, or answers with something OrderRun cannot use, nothing is brought in. Recent lookups on Order intake shows the reason and what followed:

  • Brought in for review: the order waits for a person to review and accept it.
  • Nothing was created or changed: OrderRun did not have that order, and still does not.
  • The order is held: OrderRun already had that order. It is held, with the reason shown on the order, and cannot be released or despatched while the hold stands.

A lookup hold is lifted in one of two ways. Look the order up again once your software is answering: when it is read, the hold is resolved. Or a Supervisor resolves the hold on the order with a reason, where the order should carry on without a fresh read.

Give your developer the short code in the reason, for example source_status_503 or schema_invalid. The developer guide says what each one means.

Events sent to your software

OrderRun sends an event when a job pack is released for an order of the connected namespace, and another when a Supervisor verifies the receiving answer to that pack. Neither says that work has started, finished or left the factory. No price, address or customer name is sent.

The Owner sees them under Events sent to your software: how many are acknowledged, waiting to be sent, and waiting for you.

  • An event your software does not acknowledge is tried again for 24 hours, then waits for you.
  • An event your software refuses waits for you at once.
  • Select Send this event again once the cause is put right. The original event is sent, unchanged, and your software recognises one it already has.
  • Send test event sends one event that describes no order and is not stored, to check the callback address.

No event is sent while the installation is not set to call out. A test event is then refused with “Not done: this installation is not set to call out, so nothing was sent.”

Change the addresses or retire the connection

Saved addresses never change. Under Change the addresses, save the new ones as a new version, send a test lookup of it and make it live. Events recorded for the earlier addresses are held. Under Move held events to the live addresses, give the reason and select Move and send.

Retire this connection ends lookups at once and stops both secrets. Events still waiting are held and are not sent. Every record stays. To connect again, create a new connection.

Who can do what

Task Who Additional conditions Related guide
Connect your own software, generate secrets, send a test lookup, make addresses live, retire Owner Real site only. A second factor from the last five minutes for every change. This guide.
Send events again, move held events, send a test event Owner Real site only. A second factor from the last five minutes. This guide.
Look an order up by its reference Supervisor A connection must be live. The order is prepared for review only. Intake.
Resolve a lookup hold with a reason Supervisor A second factor from the last five minutes. Amendments.

Fields

Field or control What to enter Checks and limits If it is refused
Source ID A short label for the connection, for example factory-erp Lower-case letters, digits, dots, hyphens and underscores, up to 64 characters, starting with a letter or digit. One connection for each source ID at a site. It cannot be changed. Choose another label. If it is already in use here, that connection exists or is retired.
Lookup address and Callback address The full https address your developer gave you A public address by name, up to 2,000 characters. No IP address, internal name, sign-in details or fragment. Ask your developer for the public https address. OrderRun does not call a private network.
Source namespace The name of the set of order references your software owns Up to 160 characters, with no control characters. Enter the namespace your developer and your rules agree on.
Order reference The reference exactly as your software has it 1 to 160 characters, kept exactly. Check the reference in your own software and enter it in full.
Reason, to move held events Why events recorded for earlier addresses should go to the live ones Up to 1,000 characters. Enter the actual reason, for example that the software moved to a new server.