Nuvolo Destination

Nuvolo logo

The Nuvolo Destination connector sends Work Orders, and optionally assets, from your Mapped graph into Nuvolo, the facilities and asset management system that runs on ServiceNow.

A typical setup looks like this: Work Orders come into Mapped from another system, such as Willow tickets. This connector notices them and creates matching Work Orders in Nuvolo, so your facilities team can work on them in the tool they already use. When the connector is set to update, later changes in Mapped are sent on to Nuvolo as well.

The connector writes into Nuvolo. It does not read Work Orders out of Nuvolo; that's the job of the separate Nuvolo Source connector.

Use Cases

One queue for technicians. Tickets raised in another system (for example Willow) show up in Nuvolo automatically, with the right type, request type, service and location.
Keep asset records in step. Assets known to Mapped can be pushed into Nuvolo's asset table, with their models and manufacturers, whenever you choose to run it.
Avoid duplicates and echoes. Every Nuvolo record the connector creates is linked back to its Mapped record, so the same Work Order is never created twice. You can also exclude Work Orders that came from Nuvolo in the first place.

How it works

Setup happens in the connector's configuration screens. Once you save, the connector runs by itself: it checks for new and changed Work Orders every two minutes. Three jobs can also be started by hand from the connector's Jobs panel.

Config

Step 1: Connect to Nuvolo (Auth)

Enter the details of the Nuvolo account the connector should use. Ask your Nuvolo or ServiceNow administrator for these.

Field	Required	Where to find it
Base URL	Always	The web address of your Nuvolo instance, e.g. `https://your-instance.service-now.com`.
Auth method	Always	OAuth2 (recommended) or Basic.
Username / Password	Always	A Nuvolo user that may read and write Work Orders, and assets if you sync them.
Client ID / Client Secret	OAuth2 only	From your ServiceNow administrator, who creates them in ServiceNow's Application Registry.

When you save, the connector tests the credentials straight away. A banner also tells you if the account can't read Nuvolo's table definitions. Setup still works in that case, but some lists further on will offer fewer suggestions.

The Settings section stays locked until credentials have been saved.

Step 2: Settings tab

The Settings section has three tabs along the top: Settings, Assets and Work Orders. A single Save button next to the tabs saves all three at once. It is only enabled once something has changed.

Connector capabilities

Option	What it does
Publish Work Orders	Main on/off switch for sending Work Orders to Nuvolo. When off, the two-minute sync does nothing.
Publish mode (required)	Create only: new Work Orders are created in Nuvolo, but a Work Order Nuvolo already has is never touched again. Create & Update: later changes in Mapped are also sent to the matching Nuvolo Work Order. If both sides changed, Mapped's version wins.
Sync assets	Allows the on-demand Publish Assets job to run. Assets are never synced automatically.
Only update assets created by Mapped	Off by default. When on, Publish Assets only updates Nuvolo assets this connector created, and never overwrites assets that came from Nuvolo. See below.

Only update assets created by Mapped. Turn this on if you also import Nuvolo assets into Mapped with the Nuvolo Source connector. Otherwise an imported asset could be written back over Nuvolo's own record, changing its name, type or location. With the setting on, an asset is updated only when its Nuvolo record carries the matching Mapped ID in its Correlation ID field. Skipped assets are reported as one warning per publish batch, with a count and a few example IDs, not as one warning per asset.

Assets created before correlation tagging. Assets this connector created before it started filling in the Correlation ID have no tag, so they look like Nuvolo's own assets. With the setting on they are skipped, and they would never get tagged, because only an update tags them. To turn the setting on safely: (1) leave it off, (2) run Publish Assets for the assets this connector created earlier, which tags them, then (3) turn it on. Any asset still untagged after that is treated as Nuvolo's own and skipped. If you do not import assets with Nuvolo Source, you do not need this setting.

Selected Buildings (optional)

Choose which buildings Work Orders may be sent for. The list shows buildings Mapped already knows from Nuvolo, usually because the Nuvolo Source connector brought them in.

Nothing selected (the default): Work Orders for every Nuvolo building in Mapped are sent. A building added to Mapped later is included automatically.
Some selected: only Work Orders located in those buildings are sent. The rest are quietly left out.

Source connectors

Choose which other connectors' Work Orders may be sent to Nuvolo. Unlike the rest of the panel, this list saves as soon as you click a toggle.

If you never set it, Work Orders from every source are sent.
Recommended: if you also run the Nuvolo Source connector, switch it off here. Otherwise a Work Order that started in Nuvolo can be written back over itself, which can undo a technician's latest edit.

Step 3: Work Orders tab

This is where you tell the connector where Work Orders go in Nuvolo and how Mapped's information becomes Nuvolo's fields. The connector writes to one Nuvolo Work Order table. The usual one is Corrective Maintenance (x_nuvo_eam_facilities_work_orders).

At the top, the connector reads the table's layout from Nuvolo. The steps below unlock once that finishes. An Import button can also copy a table setup from another Nuvolo connector in your organization, which saves you entering it twice.

The steps, in order:

Field mappings. For each piece of Work Order information in Mapped (name, description, dates, requester, location, related asset and so on), pick the Nuvolo field it goes into. Suggested defaults are filled in where the connector can work them out. Fields that Nuvolo fills in itself, such as the Work Order number, are never offered, because the connector must not overwrite them.
- The Work Order type must be mapped. Without it no Work Order can be sent.
Enum mappings. Some Nuvolo fields only accept values from a fixed list, such as Status, Work Order Type, Request Type, Service Needed and Sub-status. You only see a tab for each list your field mappings actually use. On each tab, match Mapped's values to Nuvolo's. For each one you can also:
- turn the mapping off, which leaves the field blank or uses a matching Nuvolo value with the same name,
- set a default that always applies, or
- set a fallback that applies only when nothing else matched.
Status today: the connector currently creates every Work Order in Nuvolo with the status Draft, and it never changes the status afterwards. Your Status mapping is saved, but it does not yet change the status in Nuvolo.
Required fields. Choose which Nuvolo fields must have a value before a Work Order is created. Also choose which location fields count: at least one of them (for example Space or Related Asset) must be filled in. A Work Order missing any of these is held back and reported, rather than created incomplete.
State transitions (read only). Shows Nuvolo's allowed status changes for this table, such as Open → In Progress, and which fields each change needs. This is for reference only and changes nothing.

Passing values through without mapping

To avoid mapping each value, go to Settings, then the Enum mappings step, and switch each tab (Status, Sub-status, Type, Request Type, Service) to Mapping Disabled. Then save once. The setup is not complete until every tab the table uses has been saved.

The destination then resolves the value in this order: a default value that always applies, then an exact match of the Mapped text against the values in Nuvolo's own choice list (ignoring case, with spaces treated as underscores; approximate names are not matched), then a fallback default (the undefined only option), then nothing. A value that finds no match leaves the field blank and logs an info message.

On the default table, three Nuvolo fields are required to create a Work Order: Work Order Type, Request Type and Service Needed. If mapping is off for one of these and nothing matches, set a default, or the Work Order is held back and reported. Other tables use whatever you choose on the Required fields step.

Status pass-through has no effect today, because the connector creates every Work Order as Draft (see the note above).

Work Order types. By default the connector only sends Corrective Maintenance Work Orders. Work Orders of other types are left out, unless your setup lists those types as allowed for the table.

Step 4: Assets tab (only if Sync assets is on)

Asset Type: match Mapped's asset types to Nuvolo's asset types.
Owning Department: choose the Nuvolo department new assets belong to.
The Nuvolo tables used for assets, models and manufacturers are fixed and shown for reference.

If Sync assets is off, this tab is hidden and nothing on it is required.

Step 5: Save

Click Save. If something important is still missing, such as a required field nobody has mapped, a confirmation box lists the problems before saving.

The connector only starts once the setup is complete. The checks are:

the credentials are entered,
a publish mode is chosen,
every enum mapping the table uses is filled in,
the Work Order type is mapped,
if asset syncing is on, Asset Type and Owning Department are mapped.

Buildings do not have to be selected.

Actions

The automatic Work Order sync (every 2 minutes)

Every two minutes the connector does the following:

Checks the setup. If something essential is missing, the run stops early with a clear message in the connector's logs, before any time is spent on data.
Looks for Work Orders. It finds Work Orders in Mapped that are new or changed since the last successful run. The very first run looks back two hours, not across all history; use the backfill to bring in older Work Orders. Only Work Orders from the source connectors you have switched on are requested.
Loads Nuvolo's reference lists. It reads Nuvolo's current types, request types, services and spaces, so values are always matched against what Nuvolo has now. On the very first run it also saves a copy of these lists to the connector, for other integrations that read them (see the Refresh Nuvolo Reference Data job).
Decides what to send. Each Work Order goes through these checks in turn:
- Wrong table: it belongs to a different Nuvolo Work Order table. Left out.
- Excluded source: it came from a source connector you switched off. Left out.
- Already in Nuvolo, mode is Create only: left out.
- Building not selected: it is located in a building you didn't pick. Left out.
- Type not allowed: its type isn't one this table accepts, for example not Corrective Maintenance. Left out.
- No location, or a required field missing: held back and reported (see below).
- Everything else is created in Nuvolo, or updated if it is already there and the mode is Create & Update. A Work Order with nothing new to send is left alone.
Links the records. Each new Nuvolo Work Order is tagged with its Mapped ID, and the Mapped Work Order is given the Nuvolo ID. That link is how the connector knows next time that the Work Order already exists, so it never creates a duplicate.
Reports a summary: how many Work Orders were created, updated, skipped and rejected.

About rejected Work Orders. A Work Order held back for a missing location or required field is reported once, not every two minutes. It is retried on each run. As soon as someone fixes it in the source system, it goes through on the next run without you doing anything.

If a run fails (for example Nuvolo is unreachable), the connector does not lose its place. The next run picks up from where the last successful one finished, so nothing is skipped.

On-demand jobs

Start these from the connector's Jobs panel. Each shows a progress bar and keeps a run history. A job does not change where the two-minute sync is up to.

Job	When to use it	What you fill in
Backfill Workorders	Re-send Work Orders the automatic sync didn't send, for example ones from before the two-hour first window, or ones fixed after a setup change. It follows exactly the same rules as the automatic sync.	Backfill Type: Date Range (Work Orders that changed in a window, default the past week) or Workorder IDs (paste Mapped Work Order IDs, usually starting `CLS`). Buildings (optional): leave empty to use your Settings selection.
Publish Assets	Push assets from Mapped into Nuvolo, along with their models and manufacturers. It only runs when Sync assets is on; otherwise it stops and says so.	Sync Type: Date Range (assets changed in a window, default the past week) or Asset IDs (paste Mapped asset IDs, usually starting `THG`). Buildings (optional). There is no "all assets" option on purpose. To load a large estate, use a wide date range, over several runs if needed.
Refresh Nuvolo Reference Data	Run this after a Nuvolo administrator adds or renames request types, job types or services. Publishing always uses Nuvolo's current lists, but the saved copy that other integrations read is only taken on the connector's first run. This job updates that copy.	Buildings (optional). It sends nothing to Nuvolo and is safe to run at any time.

For the Buildings field, enter Nuvolo building IDs (sys_ids), separated by commas. Leave it empty to use the buildings chosen in Settings, or every Nuvolo building in Mapped if none are chosen.

Troubleshooting

What you see	Likely cause	What to do
The connector shows as stopped or won't start	The setup is incomplete (see Step 5)	Open Settings. Check that a publish mode is chosen, the Work Order type is mapped and every enum tab is filled in. Then Save.
No Work Orders appear in Nuvolo	Publish Work Orders is off; the Work Orders aren't Corrective Maintenance; their buildings aren't selected; or their source connector is switched off	Check each of these in Settings. Then run Backfill Workorders for the affected dates.
"Rejected … missing required fields, no location" in the logs	The Mapped Work Order has no space or asset, or no value for a required field	Fix it in the source system; it is picked up on its own. Or loosen the Required fields step if the requirement is too strict.
An edit made in Nuvolo got reverted	Nuvolo Source is bringing the Work Order into Mapped, and this connector is writing it back	Switch Nuvolo Source off under Source connectors.
Work Orders are always Draft in Nuvolo	This is current behaviour: Work Orders are created as Draft and status is not yet sent from Mapped	Expected. Change the status in Nuvolo itself.
A new Nuvolo service or request type isn't offered in an enum mapping tab	The tab's list was loaded before the change	Reload the Settings page. To also update the saved copy other integrations read, run Refresh Nuvolo Reference Data.
"N asset(s) were not updated because their Nuvolo record has no matching correlation_id"	Only update assets created by Mapped is on, and those Nuvolo assets were not created by this connector, or were created before correlation tagging	Expected for Nuvolo's own assets. For assets this connector created earlier, turn the setting off and follow the steps under Assets created before correlation tagging in Step 2.
"Ignoring field mapping(s) …" warning	An older setup maps a field Nuvolo fills in itself	Open Settings and click Save. The mapping is removed automatically.

Mapped Concepts

This connector does not create new things in your graph. It reads existing entities and adds a Nuvolo identity to each one it sends.

Mapped entity	Read from the graph	Written back
`WorkOrder`	Name, description, status, type, request type, service, dates, requester, and the place or asset it relates to	An external identity holding the Nuvolo Work Order's sys_id
`Thing` (asset)	Name, asset tracking ID, serial number, type, owning department, model, manufacturer, location	An external identity holding the Nuvolo asset's sys_id
`Building` / `Space`	The Nuvolo identities Nuvolo Source added, used to work out where each Work Order goes in Nuvolo	Nothing

Asset field mapping

There is no editable asset field mapping table. Which Mapped field feeds which Nuvolo field is fixed in the connector. The only things you configure are the two value mappings on the Assets tab, Asset Type and Owning Department.

The connector uses three Nuvolo tables. All three table names are fixed and cannot be changed.

Purpose	Nuvolo table	Fields the connector writes
Assets	`x_nuvo_eam_facilities_devices`	See the mapping tables below.
Manufacturer reference table	`x_nuvo_eam_company`	`name`, `description`, `externalId` (the Mapped manufacturer ID), and `manufacturer` set to true.
Model reference table	`x_nuvo_eam_facilities_models`	`name`, `description`, `external_id` (the Mapped model ID), `manufacturer` (the Nuvolo manufacturer record) and `asset_type`.

Manufacturers and models are written before the assets that use them. The connector first looks for an existing manufacturer or model with the same name and only creates one if none is found.

Customizable in the connector configuration

Nuvolo field	Mapped field	Where you set it
`asset_type`	`exactType`	Asset Type on the Assets tab: match each Mapped asset type to a Nuvolo asset type. Required. Assets whose type is not matched are skipped, and the log names the unmatched types.
`department`	Name of the first `isResponsibilityOf` entry	Owning Department on the Assets tab: match Mapped department names to Nuvolo departments. Required.

Each of these two mappings can also use a default value for anything unmatched, or be turned off.

Fixed mappings (not customizable)

Nuvolo field	Mapped field	Notes
`sys_id`	`urn:nuvolo:asset:id` identity	Present only once the asset is linked to Nuvolo. Without it, the asset is created.
`asset_tag`	`assetTrackingID`
`serial_number`	`serialNumber`
`short_description`	`urn:willowinc:twin:name` identity if present, otherwise the asset `name`
`name`	The asset's customer ID identity (for example the Willow twin ID)	Assets with neither a Nuvolo ID nor a customer ID identity are skipped.
`correlation_id`	The Mapped asset ID	Lets the connector find an asset it already created, rather than create a duplicate.
`asset_location`	The asset's location: its Nuvolo `elocation` identity if present, otherwise its Nuvolo `space` identity	Only assets located in the selected buildings are sent.
`model_name`	`hasDeviceModel`	The model is found by name, or created.
`asset_manufacturer`	`manufacturedBy`	The manufacturer is found by name, or created. Assets with no model or manufacturer use `DEFAULT_MANUFACTURER` and `DEFAULT_MODEL_<manufacturer>`.
`install_status`, `operational_status`	Fixed value `1`	Sent on create only. Never changed on update, so Nuvolo keeps control of asset state.

Assets are sent only when the Publish Assets job is run, and only when Sync assets is on.

Graph Diagram

In Nuvolo, each created Work Order carries its Mapped ID in the standard ServiceNow Correlation ID field.

Sample Code

Query Work Orders

Read more about how to query Work Orders in the Mapped Graph.

{
  workOrders(filter: { connectedDataSourceId:{ eq: "your-connector-Id"}}) {
    id
    name
    mappingKey
    summary
    description
    jobStatus
    jobSubStatus
    jobPriority
    jobType
    sector
    dueDate
    dateClosed
    externalDateCreated
    externalDateUpdated
    problemDescription
    resolutionDescription
    isReportedBy {
      name
      emails {
        address
      }
    }
    isCreatedBy {
      name
      emails {
        address
      }
    }
    isClosedBy {
      name
      emails {
        address
      }
    }
    hasAssignee {
      name
      emails {
        address
      }
    }
    hasAssignedGroup {
      name
      hasMember {
        name
      }
    }
    relatesTo {
      __typename
      ... on Building {
        id
        name
      }
      ... on Floor {
        id
        name
        level
      }
      ... on Space {
        id
        name
        exactType
      }
      ... on Thing {
        id
        name
        exactType
      }
    }
    identities {
      __typename
      ... on ExternalIdentity {
        value
        scope
      }
    }
  }
}

Use Cases​

How it works​

Config​

Step 1: Connect to Nuvolo (Auth)​

Step 2: Settings tab​

Connector capabilities​

Selected Buildings (optional)​

Source connectors​

Step 3: Work Orders tab​

Passing values through without mapping​

Step 4: Assets tab (only if Sync assets is on)​

Step 5: Save​

Actions​

The automatic Work Order sync (every 2 minutes)​

On-demand jobs​

Troubleshooting​

Mapped Concepts​

Asset field mapping​

Graph Diagram​

Sample Code​