Try, check and publish a mapping

A document mapping is worth testing in three ways before workflows run it. Try it shows what a sample document becomes. Check against Nobly Insight shows whether the destination accepts that result. A workflow test then runs the whole pipeline on the draft.

​

Prerequisites

You need mappers.view to try and check a mapping, and mappers.manage to publish it or restore a version. Expression rows only run in Try it if you hold mappers.manage or workflows.manage; see Expression rows.

​

Try a sample document

The Try it tab at the bottom of the editor runs a sample through the draft as it is on screen, on every edit. Nothing is saved, and nothing is sent to Nobly Insight. The result also shows:

• Fields not written, each with the reason. A reason can be that the incoming property is empty, or that the row does not apply to this document type.
• Incoming properties that no rule or row reads. With pass-through off, nothing of them is sent. Check this list for a property that the sender renamed.
• This document would stop before upload when a row’s empty policy, a validation, or the document type rules stop the document. In a workflow, the run then fails with that explanation, and nothing is sent.

Test more than the happy path. Try a sample with a missing mandatory value, an unknown code for each lookup, and one sample per document type your rules can produce.

​

Expression rows

An expression row runs C# code with the environment’s identity, and it can read secret global variables. For that reason, expression rows are only evaluated in Try it for people who may already put code into live runs: holders of mappers.manage or workflows.manage. For anyone else, the result notes that expression rows were not evaluated, and those rows show as stopped.

​

Check against Nobly Insight

Below the result, Check against Nobly Insight compares the mapping with what Nobly Insight reports for a document type, before any upload is tried. Leave Document type empty to check the type your sample resolved, or enter another type. Then choose Check. The check covers every keyword the mapping can write for that type: field rows that apply to it, values its rules set, and keyword records. For each, it shows whether the type has the keyword, in which group, and whether it is required, hidden or read-only. It also lists:

• keywords the type requires that nothing in the mapping writes, because every upload of that type would stop on them
• the same keyword written under two names

The verdict matches the upload’s own validation, one keyword at a time, before you spend a run on it. In the example above, Customer name and Year have rows that apply to all documents. The Claim correspondence type does not have those keywords. To fix the mapping, set Applies to on those rows to the document types that have them, then check again.

​

Publish

Workflows run a mapping’s published version. Saving only changes the draft. To make the draft live, choose Publish and confirm. From then on, every workflow that names the mapping uses the new version. A run picks up the published version when it reaches its Map to Insight document step.

• Publish a mapping before the workflow that starts naming it. A Map to Insight document step whose mapping has never been published fails every document, unless a classic mapper of the same name exists (see Classic mappers).
• A run in the batch named Testing runs mapping drafts. That is what guided tests use, so you can test a draft end to end. Don’t use Testing as a batch name for production submissions.
• If someone else saved the mapping after you opened it, saving or publishing is refused, and the message names who changed it. Reload the page and apply your changes again.

The Versions tab lists each published version, its date and who published it. The version workflows run is marked runs now. Copy into the draft replaces the draft with an earlier version. It publishes nothing: test the restored draft, then publish it. You can only delete a mapping that no workflow names. The refusal lists the workflows that still use it.

​

Use the mapping in a workflow

Add a Map to Insight document step before the upload step, and choose the mapping in its MappingName list. Below the step description, Open the mapping opens it in a new tab. The panel also says which version workflows run and whether the draft has unpublished changes. The step turns the item into the document Nobly Insight receives. The item’s own properties are not changed. The steps after it work with the result: When the mapping stops a document, the step fails with the explanation and the workflow takes its exception path. The run in States shows the partial result on its Document tab, so you can see which row stopped it. See States and recovery. By default, the upload is strict when pass-through is off. A keyword the document type does not have fails the upload instead of being dropped. The upload step’s setting for unmapped keywords can override this per workflow.

​

Classic mappers

Mappers created before document mappings existed are listed as Classic mapper. They still run where workflows use them, and nothing is converted automatically.

• Open shows a classic mapper read as a mapping. Each keyword becomes one copy row, pass-through is on, and the document type comes from the sender. Save as a mapping creates a mapping with the same name. From then on, the list shows the mapping instead of the classic mapper.
• A Map to Insight document step that names the classic mapper keeps running the classic mapper until the mapping of that name is published.
• An upload step that names a classic mapper itself, without a Map to Insight document step, keeps working as before.
• Classic mapper editor at the top of the list opens the old editor, for workflows that still depend on it.

To move a workflow onto a mapping: open the classic mapper, save it as a mapping, and refine the rows. Then check it against each document type, publish it, and add a Map to Insight document step to the workflow. Test the workflow before you publish it.

​

Where to read next