Nuvolo Source

The Nuvolo Source connector imports Nuvolo CMMS Building, Floor, Space and Work Order data into the Mapped Graph. It brings in the place hierarchy for the buildings you select, polls Nuvolo Work Orders every minute, and supports on-demand historical backfill. Optionally, it can also import your Nuvolo assets as Things placed in the spaces you have imported (see Importing assets).

This connector only reads from Nuvolo. To send Work Orders from Mapped into Nuvolo, use the Nuvolo Destination connector.

Use Cases

• CMMS visibility in Mapped: Query Nuvolo Work Orders alongside occupancy, asset and building data from your other connectors.
• Consistent places: Build the Building / Floor / Space hierarchy in Mapped from your Nuvolo records.
• Work Order correlation: Link each Work Order to its people, assignment group, place and asset.

---

How it works

Setup happens in the connector's configuration screens. After you save, the connector brings in Work Orders every minute by itself. You add your locations by reviewing them in the Buildings, Floors and Spaces sections. For older history, run the Backfill Workorders job. If you import assets, run the Backfill Assets job to load your existing assets.

---

Configuration

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 can read your locations tables and Work Order table.
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 tells you if the account can't read Nuvolo's table definitions. You can still set up the connector in that case, but it will suggest fewer fields.

Everything else stays locked until credentials are saved.

Step 2: Settings tab

The Settings section has four tabs: Settings, Locations, Assets and Work Orders. One Save button next to the tabs saves all four at once.

Connector capabilities

Option	What it does
Poll Work Orders	Turns the every-minute Work Order sync on or off. It starts off, so remember to switch it on.
Poll assets	Keeps imported assets up to date as they are created or updated in Nuvolo. It starts off. It does not load your existing assets: for those, run the Backfill Assets job and choose full (see Importing assets). Review the Assets tab before you save with it on.
Buildings to Poll (optional)	Limits the sync to Work Orders in these buildings. The list shows buildings Mapped already knows from Nuvolo, including ones another connector added. Leave it empty to sync Work Orders for every building you have imported in the Buildings section.

Step 3: Locations tab

Choose which Nuvolo field supplies a few details for each kind of place. Suggested defaults are filled in for you:

Place	Detail	Default Nuvolo field
Building	Name	name
Building	Code	u_real_estate_id
Floor	Name	name
Floor	Level	floor_level
Space	Name	display_name

A Sample locations preview shows real records from your Nuvolo instance, so you can check the result before saving. Everything else about a place (its address, its parent, its Nuvolo IDs) is handled automatically.

Step 4: Work Orders tab

The connector reads Work Orders from one Nuvolo table. The usual one is Corrective Maintenance (x_nuvo_eam_facilities_work_orders). The connector first reads that table's layout from Nuvolo. An Import button can also copy the setup from another Nuvolo connector in your organization.

Under Field mappings, choose which Nuvolo field fills each piece of Mapped Work Order information. Defaults are filled in for you (see the reference table at the end of this page). Two mappings are required:

• Name, which carries the Work Order number, e.g. FWKD0002308, and
• Status.

Where a Work Order is. The connector looks for the Work Order's space first, then its work location, then its asset's location. If you list your own location fields under relatesToPlace (for example floor or building fields, for Work Orders that have no space), those are checked first, in the order you give. The Work Order is linked to the most specific place found.

Assets tab (optional)

The Assets tab sits between Locations and Work Orders and works like the Work Orders tab. Asset types are loaded from Nuvolo when you first open the tab, so a loading message shows briefly before you can edit anything. Banners at the top remind you that polling only keeps assets up to date (run Backfill Assets to import your existing ones), that assets created by Mapped are never imported, and, while Poll assets is off, that imported assets are not kept up to date until you switch it on.

Table settings. The asset table, x_nuvo_eam_facilities_devices, is fixed and shown for reference. There is no Import button on this tab.

Import filters. These decide which assets are left out. A one-line summary under the card title says what is excluded.

Setting	What it does
Excluded categories	Asset type categories to skip entirely.
Excluded asset types	Individual asset types to skip, for exceptions within a category.
Import assets with no asset type	On by default. Turn it off to skip assets with no type.
Excluded install statuses	Install statuses to skip. The suggested default is the retired status.

The first time the tab loads, the connector looks at your Nuvolo asset types and pre-checks suggested exclusions, each with its evidence (asset counts and how concentrated they are). A type is suggested when it looks like a placeholder: a very large type (1,000 assets or more) with almost all of its located assets in a single location, or a type whose category or sub-category is Unbound, Placeholder, Unassigned or Room (or whose category ends in Physical Building Space). Suggestions only take effect when you save, and once you have saved, your own choices are kept and never overwritten. Review them before saving.

Field mappings. Choose which Nuvolo field fills each piece of asset information: name, serial number, asset tag, description, install date, and the manufacturer and model names. Defaults follow the usual Nuvolo columns. A name mapping is required.

Saving. You can save asset settings while Poll assets is off. Saving them is what allows the Backfill Assets job to run, so you can import your existing assets before you switch polling on. With Poll assets on, Save stays disabled (with the reason shown) until you have opened the Assets tab and its type list has loaded; use Retry if loading failed. Save is also disabled if you have excluded so many individual types that the request to Nuvolo would be too long: exclude whole categories instead, or remove some exclusions.

When a save changes your filters or field mappings, or switches Poll assets on, a confirmation window opens first. It shows how the assets in Nuvolo break down: the total, those that cannot be imported (no location, or created by Mapped), those excluded by your filters, and those outside your imported spaces. It ends with After filtering, N assets are set to import. On large instances the count can take a little while. If it fails you can still choose Save anyway; Cancel leaves everything as it was. If no spaces are imported yet, the window says so, because no asset can be placed until they are.

Step 5: Save

Click Save. The connector only starts once:

• Settings have been saved at least once,
• the credentials are complete, and
• when polling is on, a Work Order table is chosen with Name and Status mapped, and
• when Poll assets is on, the asset settings have been saved, including a name mapping.

Step 6: Import your locations (Buildings → Floors → Spaces)

The Buildings, Floors and Spaces sections each show a review list of what Nuvolo has. Work through them in order:

1. Buildings. Every active Nuvolo building is listed. Select the ones you want, pick the Site each belongs to, and save. A building Mapped already knows keeps the Site it had.
2. Floors. Only floors of buildings you have already saved appear. If this list is empty, save your buildings first. Each floor needs a name and a level before you can select it. Your organization's merge rules may fill these in for you.
3. Spaces. Only spaces on floors you have already saved appear. Each space comes in as a Space, or you can mark it as a Workspace. Its floor area comes with it when Nuvolo has one. Each space also shows its building's Nuvolo ID and name, so you can search or filter the list by building. If you rename a building in Mapped, import Spaces again: its spaces then show as changed until you save them.

You can come back to these lists at any time to add more places, or to bring in changes made in Nuvolo.

---

Actions

The automatic Work Order sync (every minute)

When Poll Work Orders is on, every minute the connector does the following:

1. Works out the time window. It takes everything changed in Nuvolo since the last successful run. The very first run looks back 4 hours. For anything older, use the Backfill Workorders job.
2. Reads the Work Orders changed in that window from your chosen Nuvolo table, a page at a time.
3. Finds where each one is, as described in Step 4. Only places in your buildings count. A Work Order with no matching place in your buildings is left out and counted in the logs.
4. Fills in the details. Status, type, request type, service and sub-status are turned into the readable names Nuvolo shows. People, the team and the related asset are looked up and linked.
5. Recognises Work Orders that started in Mapped. If a Work Order was created in Nuvolo by the Nuvolo Destination connector, the connector links it back to the original Mapped record instead of adding a second copy.
6. Adds the Work Orders to Mapped, or updates ones it already has.

If a run is interrupted (for example Nuvolo is unreachable partway through), the connector doesn't skip anything. The next run starts again from the same point.

The Backfill Workorders job (on demand)

Start it from the connector's Jobs panel. It shows a progress bar and keeps a run history. It does not change where the every-minute sync is up to.

Backfill Type	What to fill in
Date range	A window of up to 60 days back. The default is the past week. Long ranges are worked through a week at a time.
Workorder Numbers	The Work Order numbers people see in Nuvolo, e.g. FWKD0002308, separated by commas.
Workorder IDs	Nuvolo's internal record IDs (sys_ids), separated by commas.

The backfill follows the same rules as the automatic sync: the same table, field mappings, buildings and location matching.

---

Importing assets

Asset import is optional. To use it:

1. Import your Buildings, Floors and Spaces first (Step 6). Only assets located in spaces you have imported are brought in. Assets with no location, or located only at building level, are left out.
2. Review the Assets tab and click Save. Switch on Poll assets if you want imported assets kept up to date.
3. Run the Backfill Assets job and choose full to import your existing assets. The job only needs the asset settings to be saved; Poll assets does not have to be on.

The automatic asset sync (every 5 minutes)

When Poll assets is on, every 5 minutes the connector reads the assets created or updated in Nuvolo since the last successful run, which keeps their details, install status and lifecycle state current. The very first run looks back 4 hours. If the sync has not succeeded for more than 7 days (for example after a long outage), the next run reads only the last 7 days and logs a warning with the date it had reached. Run Backfill Assets to cover the earlier period.

If a run is interrupted (for example Nuvolo is unreachable), the next run reads the same period again, so nothing is skipped. Each run writes one line to the connector's logs:

• Asset import: N imported, M outside merged spaces this run: assets were read. Outside merged spaces counts assets that were read but not imported because they are not in a space you have imported.
• Asset import: caught up: there was nothing new to read.
• Asset import: interrupted after N imported; the next run re-reads this window: the run was cut short.

The Backfill Assets job (on demand)

This job imports your existing assets. Run it after you first save the asset settings, and again whenever you widen the filters: filters apply going forward, so assets in a category, type or status you un-exclude are only picked up when you run the job again. Start it from the Jobs panel and choose a Backfill Type:

Backfill Type	What it does
dateRange (the default)	Imports assets created or updated in the window you pick (as early as 2000-01-01). Useful after a sync outage or after un-excluding a type. It works through the window 30 days at a time and reports progress per batch. If a batch fails, the log names its start date: run the job again from that date.
full (Full import)	Imports every asset that matches your filters. Use it for your first load.

A full import first counts the matching assets so its progress bar is meaningful, then logs a progress line every few pages (for example Full import: 25,000 read, 3,000 imported so far) and a summary when it finishes. Large estates can take a long time. If the job stops, the log says how far it got: run it again with full. Assets already imported are updated rather than duplicated, so re-running is safe. Neither mode changes where the automatic asset sync is up to.

Which assets are imported

• Assets not created by Mapped. An asset created by the Nuvolo Destination connector carries a correlation ID and is never imported back.
• Assets in a space you have imported.
• Assets not excluded by your category, type or install status filters.

Assets already imported are not removed when you exclude them later, and retired or deleted assets are not yet retired in Mapped. An asset that moves into an excluded install status (for example retired) stays in Mapped at its last imported state.

Once you have saved asset settings, Work Orders link to an asset only after that asset has been imported. A Work Order that mentions an asset outside the import (no location, not in an imported space, or excluded by your filters) has no asset to link to.

Using Nuvolo Destination as well? Turn on its Only update assets created by Mapped setting, following the steps in the Nuvolo Destination guide. Assets it created before it started tagging them with a correlation ID look like Nuvolo's own assets and would otherwise be imported.

---

Troubleshooting

What you see	Likely cause	What to do
The connector won't start	Settings were never saved, credentials are missing, or Name/Status aren't mapped	Open Settings, finish the Work Orders field mappings, and click Save.
"The poll was denied because polling is disabled"	Poll Work Orders is off	Switch it on in Settings and click Save.
No Work Orders in Mapped	Polling is off; the Work Orders are older than 4 hours; or their buildings aren't imported or selected	Check Settings and Buildings, then run Backfill Workorders for the dates you need.
"Skipping N workorders without a resolvable place"	Those Work Orders have no space, work location or asset location the connector can match	Fill in a location in Nuvolo, or add your own location fields under relatesToPlace. Then backfill.
Asset import fails with an error about no spaces	No Spaces have been imported yet, or their Nuvolo location details could not be loaded	Import your Buildings, Floors and Spaces, check the connection, then run again.
Existing assets do not appear after switching on Poll assets	The sync only reads assets as they are created or updated	Run the Backfill Assets job and choose full.
Few or no assets after running Backfill Assets	The assets are outside your imported spaces, or your filters exclude them	Check the outside merged spaces count in the job's log lines. Import more spaces or loosen the filters on the Assets tab, then run Backfill Assets again.
A log warning says asset polling has only read changes up to a date more than 7 days ago	The asset sync was down for a while	The sync now reads only the last 7 days. Run Backfill Assets (full, or dateRange for the missing period).
Placeholder or "unbound" assets appeared	Their type was not excluded	Exclude the category or type on the Assets tab and Save. Assets already imported are not removed.
The Floors or Spaces list is empty	The level above hasn't been saved yet	Save your Buildings (or Floors) first.
A floor can't be selected	Its name or level is empty	Enter them in the list, or set Merge Rules.

---

Mapped Concepts

Work Order field mappings (defaults)

Mapped field	Default Nuvolo field	Notes
name	number	Required.
description	description
summary	short_description
sector	u_request_type	Converted to Nuvolo's readable label.
problemDescription	u_service_needed	Readable label.
resolutionDescription	resolution_detail
jobPriority	priority
jobStatus	state	Required. Readable label.
jobSubStatus	substate	Readable label.
jobType	work_order_type	Readable label.
dueDate	due_date
dateClosed	closed_at
externalDateCreated / externalDateUpdated	sys_created_on / sys_updated_on
hasAssignee	assigned_to	Linked to a Person.
hasAssignedGroup	assignment_group	Linked to a PeopleGroup, with the assignee as a member.
isReportedBy	reported_by	Person.
isCreatedBy	opened_by	Person; uses the reporter when the creator has no email.
isClosedBy	closed_by	Person.
relatesToThing	asset	Linked to a Thing (the related asset).
relatesToPlace	(optional, ordered list)	Checked before the built-in space → work location → asset location order. One place is linked: the most specific one found.
hasActualCost / hasEstimatedCost	total_cost / estimated_cost	Only added when the value is a real number, 0 included.

Each Work Order also records the Nuvolo table it came from. Nuvolo Destination uses that to avoid writing a Work Order back into a different table.

Entities created

Nuvolo source	Mapped entity	Notes
x_nuvo_eam_building (active)	Building	Reviewed and merged in the Buildings section, under the chosen Site.
x_nuvo_eam_floor (of merged buildings)	Floor	Carries a level.
x_nuvo_eam_space (of merged floors)	Space or Workspace	Carries grossArea when Nuvolo has an area with a recognised unit.
The configured Work Order table	WorkOrder	Merged directly on every poll and backfill.
sys_user (assignee, reporter, creator, closer)	Person, with Email when available
Assignment group	PeopleGroup
x_nuvo_eam_facilities_devices (related asset)	Thing	When you import assets, each becomes a generic Thing with the Nuvolo ID and asset number as identities; the name, serial number, asset tag, description and install date from your field mappings; assetLifecycleState (the install status); assetType and installStatus extended properties; and the space it is in, updated when the asset moves in Nuvolo.
Asset model and manufacturer	DeviceModel and Company	Linked to an imported asset when Nuvolo has them. Models are kept per manufacturer.

Every Building, Floor and Space carries urn:nuvolo:* external identities: its sys_id, plus its number where available. Work Orders use these to find their place, so a place doesn't have to be an imported entity for a Work Order to link to it.

Graph Diagrams

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
      }
    }
  }
}

More GraphQL samples

Buildings, floors and spaces this connector has merged:

{
  buildings(filter: { connectedDataSourceId: { eq: "<CONNECTOR_ID>" } }) {
    id
    name
    floors {
      id
      name
      level
      spaces {
        id
        name
        exactType
        grossArea {
          quantity
          unit
        }
      }
    }
  }
}

Timeseries

This connector creates no Points or timeseries data.