Polinode

Passive Data

Please note that the Passive Data Module needs to be enabled for your organization before you will be able to use it. There is an additional cost associated with this module that depends on the number of employees that you will be activating it for.

The Passive Data Module is desinged to make it easy to conduct Passive Organizational Network Analysis with the Polinode platform. Generally an Account Manager from Polinode will work with you to configure and setup the Passive Data Add-On.

Sources

The first tab is Sources, where you manage every passive data source available to your organization. This tab is available to Admin users in your organization. It presents all sources — both Polinode's built-in integrations and any custom sources — in a single catalogue of cards, sorted alphabetically. A card keeps its position in the grid as its status changes, so it's easy to find a source again later.

At the top of the catalogue you'll find a search box ("Search sources") and a row of filters with live counts so you can narrow the list to All, Installed, Built-in, Public or Your Org sources. The tab opens on Installed by default, so the sources you're already using are front and centre; switch to All to browse the full catalogue. Each card carries badges that tell you at a glance what a source is — Built-in, Custom, Public, Your Org and Update available. A source's install and connection state is conveyed by its status line and its primary button rather than by a separate badge.

Built-in Sources

The built-in sources Polinode offers are:

  1. Office 365 Directory: When setting up the Office 365 data sources initially, you need to first connect to the Directory. This provides Polinode with a list of either all the employees in your organization, or, if setup just those employees in a Directory Group that you have setup. We use this data to collect metadata for these emails, e.g. email and calendar metadata. Once the Office 365 Directory is setup, you will be able to connect to any or all of the Email, Calendar and People data sources for Office 365.
    When you setup Office 365 Directory as a source you have the ability to specify one or more Office 365 Directory Groups for which to activate it. If none is specified then it will be active for everyone in the organization.
    The Directory also defines who metadata is collected for: email, calendar, People and Teams metadata is collected for everyone the Directory currently includes. When an employee leaves the Directory (or the configured Directory Groups), collection for them stops from the next daily sync. If your employee attributes come from an HR source such as Workday (see Employee Attributes Source below), employees that source marks as terminated are also excluded from collection, even while their account remains in the Directory.
  2. Office 365 Email: Once connected, the Office 365 Email data source allows Polinode to collect and store email metadata for the employees that you have configured via the directory integration. Polinode will then retrieve this metadata on a daily basis.
  3. Office 365 Calendar: Similar to Office 365 Email metadata, this data source allows Polinode to collect Office 365 Calendar metadata on a daily basis.
  4. Office 365 People: Office 365 also makes available a People API that we can use to retrieve and store the Top X connections based on a range of sources for each individual setup in the Directory. Here we can specify X in Polinode when we set the integration up for you but it's normally 20. We retrieve and store this data automatically once a week.
  5. Microsoft Teams: Our Teams integration can be setup to collect posts in Teams channels and/or private messages (one-to-one chats, group chats and meeting chats), in any combination — including private messages only. Private message collection follows the same scope as your Office 365 Directory setup: if the Directory source is limited to particular Directory Groups, private message metadata is collected only for members of those groups; otherwise it covers the whole tenant. These options are configured by Polinode as part of your setup. Data is collected from the date it is setup and historical data is not retrieved.
  6. Slack: Our Slack integration can be setup to include only posts in public channels or it can optionally also include private DMs and private channels. If the latter is setup, individual user consent is required which Polinode will request and handle. Historical data can be imported.
  7. Workday: Our Workday integration imports employee attributes (job title, level, function, location, worker type and so on) and manager reporting lines from a custom report in your Workday tenant, refreshed once a day. See the Connecting Workday section below for full setup details, including the report column requirements.

In addition to these built-in sources you can also define your own Custom Sources — see the Custom Sources section below.

ENTERPRISE USERS

There are quite a few options available when connecting to the various passive data sources available. Your account manager can talk you through them and help you to determine the best setup to achieve your objectives.

Source Lifecycle

Every source — built-in or custom — follows the same lifecycle: Install → Connect → Manage → Disconnect → Uninstall. The primary button on each card reflects the next step, and its style tells you where the source stands at a glance: Install is a solid blue button (the catalogue's main call to action), Connect is a solid green button, and Manage is a quiet grey outline once the source is already working. On a source that is connected, Uninstall is promoted to the dominant (red) action on the card and Manage moves into the card's overflow (⋮) menu. The remaining actions always live in that overflow menu, with destructive actions kept at the bottom.

  1. Install: Adds the source to your organization so you can configure it. You can install sources in any order, even before their prerequisites are ready — installing a source doesn't start collecting any data on its own.
  2. Connect: Authorises and activates the source so that Polinode begins collecting data. Some sources have dependencies and their Connect action stays disabled until the prerequisite is met — for example, Office 365 Email cannot be connected until the Office 365 Directory has completed its first import (the card will show a hint such as "Complete Directory Import First"). You can still install a dependent source at any time; only Connect waits for the dependency.
  3. Manage: Opens the source's settings. For built-in sources this includes the option to route the source's traffic through Polinode Datashield (if your organization has Datashield enabled — see the Polinode Datashield section below). For custom sources this opens the full detail view (credentials, recent activity and errors).
  4. Disconnect: Stops data collection for the source while keeping its configuration, credentials and already-collected data. You can reconnect the source later to resume collection — nothing is deleted.
  5. Uninstall: Removes the source entirely. All collected metadata for that source is removed and this cannot be undone. The deletion runs in the background — the card shows Being deleted... until removal completes, which can take a while for sources with a lot of collected data. Uninstall is the only action that deletes data; use Disconnect if you simply want to pause collection.

Each card also shows the source's current status, for example Ready to connect, Soon to run, Waiting for data, Running, Active, In error or Being deleted..., along with the date of the most recent successful import where applicable. For sources that import per employee, the Running status also shows live progress through the import — for example "Running... 250 of 1,000 employees". If a source's most recent run failed, the card also shows the error message beneath the status line, so an Admin can see the cause at a glance without opening the source.

Connecting Workday

The Workday source uses Workday's standard RaaS ("Report as a Service") pattern: your Workday administrator builds a custom report containing the fields you want to share, enables it as a web service, and Polinode polls that report's URL once a day. You control exactly which fields and which workers leave Workday — the report definition and Workday's own domain security decide what Polinode can see.

Workday can be connected in either of two ways, whichever your organization prefers:

  1. Directly: both the report URL and the ISU username and password (see Step 1 below) are entered in Polinode. The password is stored encrypted and never displayed again.
  2. Via Polinode Datashield: only the report URL is given to Polinode — the ISU credentials live solely in your organization's own Datashield deployment and Polinode never receives them. See Step 4 below and the Polinode Datashield section under Settings.

Step 1: Create an Integration System User (ISU)

In Workday, your administrator should:

  1. Run the Create Integration System User task and create a dedicated user for Polinode (for example polinode_isu). Set Session Timeout Minutes to 0 and tick Do Not Allow UI Sessions.
  2. Run Maintain Password Rules and add the ISU to System Users exempt from password expiration, so a routine password rotation doesn't silently break the feed.
  3. Run Create Security Group and create an Integration System Security Group (unconstrained is simplest; a constrained group simply limits which workers the feed can ever see), then add the ISU to it.
  4. Grant the security group Get access to the domains that back your report fields — typically Worker Data: Public Worker Reports, Worker Data: Workers, Person Data: Work Contact Information and Job Information — then run Activate Pending Security Policy Changes.
  5. If your tenant uses authentication policies, ensure the ISU's security group is allowed to sign in with User Name Password. You can also restrict the ISU to Polinode's egress IP addresses (ask your Account Manager for the current list) via Maintain IP Ranges and Manage Authentication Policies.

WARNING

Workday returns blank values — not errors — for fields the ISU lacks domain permission for. If a column comes through empty for every worker, the missing domain grant is almost always the cause. Polinode's connection test flags columns that are empty on every row for exactly this reason.

Step 2: Build the report

Create a custom report of type Advanced (ideally owned by the ISU — the report owner's username is part of the URL, and tenant refreshes reset ownership, which breaks the URL). On the report:

  1. Use a flat, single-row-per-worker layout. Do not use group column headings — nested columns cannot be imported.
  2. Set each column's Column Heading Override XML Alias to the Polinode alias for that field (see the column reference below). Matching is forgiving of case and underscore differences (CostCenter_Id matches costCenter_id), but we recommend using the documented aliases exactly.
  3. Filter to the population you want to share (for example active workers only). The report is treated as the authoritative population: when Workday supplies employment status (see Employee Attributes Source below), workers present in the report are automatically treated as active — no status column required — workers who later drop out of the report are marked terminated in Polinode, and a worker who returns to the report (for example a rehire) is reactivated.
  4. Tick Enable As Web Service (on the Advanced tab), and enable Optimized for Performance if the report allows it.
  5. Share the report with the ISU (Share tab → share with specific authorized users and groups).
  6. Set the ISU account's locale to en_US so dates are formatted consistently.

From the report's related actions choose Web Service → View URLs and copy one of the links (any format — Polinode always requests the JSON format). This is the URL you paste into Polinode.

Step 3: Report columns

Polinode matches columns by their XML alias. Three aliases are special:

Alias Required Purpose
email Yes The worker's work email — Polinode's identity key
manager_employeeId No The manager's Employee ID, used to build reporting lines (preferred)
manager_email No The manager's email — a fallback when Employee ID isn't available

Every other scalar field of Polinode's employee record is addressable with an alias equal to the field's API name, using an underscore for nesting. Commonly used aliases include employeeId, firstName, lastName, preferredName, department, division, team, costCenter_id, costCenter_name, companyName, employment_jobTitle, employment_businessTitle, employment_jobCode, employment_jobLevel, employment_jobFamilyGroup, employment_jobFamily, employment_workerType, employment_workerSubtype, employment_type, employment_status, employment_startDate, employment_originalHireDate, address_city, address_state, address_country and location_name. The list matches the field names of Polinode's public Employees API (see the API documentation) with dots replaced by underscores, with a small number of deliberate exceptions:

  • The manager aliases in the table above are reserved names: manager_employeeId and manager_email do not correspond to API field names (the API exposes only manager.id, and there is no manager email field in the API).
  • Internal API fields — those marked ⁱ in the API documentation, such as _id — are never valid column aliases. The identity column is email (matched like any other alias, so Email also works) and the external identifier field is employeeId.
  • Array-valued API fields (orgLevels, groups, skills, certifications, languages and so on) cannot be ingested from a flat report — only scalar fields have aliases, and a column named after an array field falls through to a custom field instead. The orgLevel_<N> and group_<Name> conventions below cover the two most common cases; structured arrays that a flat report can never express (such as skills or certifications) can instead be populated via the Employees API, alongside the Workday sync.

Worker taxonomy — three separate fields. Workday's Time Type (Full time / Part time) maps to employment_type. Worker Type (Employee / Contingent Worker) maps to employment_workerType, and Worker Subtype (Regular, Fixed Term, Intern and any other values your tenant defines) maps to employment_workerSubtype. Do not map Worker Type to employment_type — its values are not valid employment types, so they would be dropped with a warning rather than stored.

Job title and business title. Workday holds two titles, and both have aliases. employment_jobTitle is the standardised title that comes from the job profile, while employment_businessTitle is the worker-level title that HR or a manager can customise — usually the one people use to describe themselves. Map whichever you want shown on nodes, or map both. employment_jobCode carries the job profile code and accepts alphanumeric codes.

Employment status is optional. When Workday supplies employment status, every worker present in the report is treated as active automatically, so an employment_status column is only needed if you want to convey other states (for example On Leave). When the column is present its value wins over the automatic default.

Supervisory organization levels. The reserved aliases orgLevel_<N> and orgLevel_<N>_code (for example orgLevel_1, orgLevel_2, orgLevel_2_code) map Workday's delivered "supervisory organization level N from top" fields into the employee's orgLevels array as { level, name, code } entries. Levels present in the report are updated on each daily snapshot; levels the report doesn't mention are left as they are.

Groups. The reserved alias pattern group_<Name> maintains membership of the group <Name>, with underscores in the alias becoming spaces — group_Senior_Leader_Cohort manages membership of the group "Senior Leader Cohort". A truthy column value (1, true, yes) makes the worker a member; a falsy or blank value means not a member. Membership of the groups the report manages is reconciled on every daily snapshot, while group names the report doesn't manage (for example ones set via the Employees API) are preserved.

Any column that is not a recognised alias automatically becomes a custom field in Polinode: a custom field definition is created from the column (with its type inferred from the values), and the values appear as node attributes in your networks. This means you can add any extra Workday field to the report — a talent segment, an engagement cohort — and it will flow through with no further configuration. The field's display label is derived from the column alias: underscores become spaces, camelCase words are split, and each word is capitalised, so CompensationGrade becomes "Compensation Grade" and Talent_segment becomes "Talent Segment". One caveat: a custom field's type and label are set once, on the first run that sees the column (the type is inferred from the sampled values), and are fixed thereafter — later values that don't match the inferred type are dropped with a warning. If the column's first pull is sparse or unrepresentative, check the created definition before relying on it.

Step 4: Connect in Polinode

On the Passive Data → Sources tab, install the Workday source and click Connect. Paste the report URL and enter the ISU username and password (the password is stored encrypted and never displayed again). Use Test Connection to validate everything before connecting — it fetches the report and shows the row count, the recognised columns, and warnings such as columns that are empty on every row.

If your organization uses Polinode Datashield, the Workday source can route through it instead: turn on Use Polinode Datashield in the connect dialog and only the report URL is collected. In this mode the ISU credentials are configured solely in your Datashield deployment and Polinode never receives them — your IT team sets this up following the Workday setup guide included in the Datashield repository documentation (docs/services/workday-setup.md), or with help from your Polinode contact.

Once connected, Polinode imports the report immediately and then refreshes it once a day. If a run fails, the source's card shows an error message describing the cause — for example invalid credentials, a report that is no longer shared with the ISU, or a report URL whose owner changed after a tenant refresh.

Reporting lines and attribute priority

When Workday is connected it becomes, by default, the source of employee attributes and reporting lines (it is the highest-priority source in the Automatic setting of both pickers under Settings — see Employee Attributes Source and Reporting Lines Source below). If you also run the Office 365 or Google Workspace directory integrations you can override this per picker at any time.

Custom Sources

In addition to Polinode's built-in integrations, Admin users can define Custom Sources — your own passive data sources that push relationship data into Polinode (for example a CRM such as Salesforce, an HRIS, or a personal LinkedIn Connections export). Custom sources appear in the same Sources catalogue as built-in sources and follow the same Install / Connect / Manage lifecycle described above.

Custom sources are defined by Source Templates. A template captures what a source looks like — its name, icon, how it authenticates, and the entities, relationships and events it can push. Once a template exists it can be installed as a working source in your organization. Polinode publishes some templates publicly (for example LinkedIn Connections), and you can also create your own.

Creating or Editing a Custom Source

Click New Custom Source on the Sources tab (or edit an existing template) to open the editor. The available fields are:

  1. Icon: An optional PNG or JPG icon shown on the source card (square images work best, maximum 1MB). Built-in sources use Polinode's bundled logos; custom sources show the icon you upload here.

  2. Name: A human-readable name for the source, e.g. "Salesforce CRM Relationships".

  3. Description: A short description of what data the source brings into Polinode. This is shown on the source card.

  4. Authentication: How external systems authenticate when pushing data:

    • Push credential (server-to-server): For systems that push data machine-to-machine. An Admin mints one or more API tokens that the external system uses to authenticate.
    • User email connect (personal export): For per-person export flows (such as LinkedIn Connections), where each employee connects their own data. For these sources credentials are issued per employee through the connect flow rather than minted by an Admin, and are keyed on the employee's verified email address.

  5. Definitions (JSON): The structural definition of the source, entered as JSON and validated live. It describes everything the source is allowed to push:

    • entityTypes — the kinds of entity the source can create. Each entity type has a key, a displayName (the entity type's own label in the source catalogue — distinct from the per-record displayName that labels an individual node, see Pushing data below), a baseKind (the underlying Polinode entity it maps to, e.g. a person), and optional identityFields (the fields used to match/deduplicate an entity) and requiredFields.
    • relationshipTypes — standing (ongoing) relationships between entities. Each has a key, displayName, a queryLabel (the label shown when building a query), an edgeAttributePrefix (the prefix applied to attributes this relationship contributes to a network edge), the sourceEntityTypes and targetEntityTypes it connects (each an array, as an edge type may connect more than one kind of entity at either end — and employee may always be used as an endpoint without being declared under entityTypes), and an optional enabledByDefault flag.
    • eventTypes — point-in-time interactions between entities (same shape as relationship types). These are aggregated into edges in the same way as built-in interaction sources such as emails or meetings.
    • batchModes — the batch/ingest modes the source supports when pushing data.

    TIP

    The Definitions JSON is an advanced field. Your Account Manager can help you author it, and you can clone an existing public template (such as LinkedIn Connections) as a starting point.

When a source is installed it takes its own complete copy of the template's definition, so an installed source is fully self-contained. Editing a template therefore never changes how any organization's already-installed source behaves — each installed source keeps running on the copy it was installed from, and its collected data is untouched. This is true for every template, including Polinode's public templates: editing one (for example to refresh its icon) does not disturb organizations that have already installed it. To pull the latest template changes into a running source, open it from the Sources tab and choose Update (see below); until you do, nothing about that source changes.

Pushing data

A Push credential (server-to-server) source receives data by POSTing batches of records to its push endpoint, authenticated with a Bearer token. Each record describes one entity, relationship, or event. An entity record has this shape:

{
  "entityType": "person",
  "identity": { "externalId": "0033Vc...", "email": "jordan.kim@example.com" },
  "displayName": "Jordan Kim",
  "attributes": { "title": "Benefits Manager", "department": "HR" }
}
  • entityType — one of the keys declared in the template's entityTypes.
  • identity — the identity field(s) used to match/deduplicate the entity (e.g. externalId, email, linkedinUrl), per the type's identityFields.
  • displayName — required for every entity except employees. This is the entity's node label in generated networks. A record without it is rejected (and reported in the batch's rejected count and validationErrors), rather than ingested as a node that would otherwise label by its internal id. The label lives at the top level of the record, not inside attributes — an attribute called name or fullName does not set the label on its own.
  • attributes — any other values for the entity, keyed by attribute name. These show on the node but are not used as its label.

WARNING

displayName is the single most common omission when first integrating a push source. If you push entities and find their nodes labeled by a long id, check that each record sends a top-level displayName — putting the name only in attributes is not enough. The Recent activity panel on the source's Manage view shows the accepted-vs-rejected counts, and the Errors panel lists the displayName is required validation errors.

Don't repeat identity fields in `attributes`

Identity fields you send under identity are already surfaced as node attributes automatically — for example identity.email shows as Email and identity.linkedinUrl shows as LinkedIn URL. Sending the same value again inside attributes (e.g. an attributes.linkedinUrl) produces a second, duplicate field on the node. Put a value in identity or attributes, not both. (A non-identity attribute that resolves a reference to something human-readable — say turning an owner id into an owner name — is fine and encouraged.)

Batches and Processing

Records are pushed in batches of up to 10,000 records; larger snapshots should be split into multiple batches that share a sourceRunId, with isFinalBatch: true on the last batch of the run. A successful push returns immediately with HTTP 202 and a batch id — the batch is then processed in the background. The response reports the batch's status along with received, accepted and rejected counts and any validationErrors, and you can poll the batch by its id until the status reaches completed (or failed). The same accepted-versus-rejected breakdown appears in the Recent activity panel on the source's Manage view.

A few details that make integrations more robust:

  • Retries are safe with an idempotency key. You may supply an Idempotency-Key header on a push; replaying the same key with the same body returns the original batch's result rather than ingesting the records twice.
  • Dry runs. Entity snapshot batches can be sent as a dry run, which validates all records synchronously and reports what would be accepted or rejected without ingesting anything.
  • Interactions can arrive before their entities. If a relationship or event references an entity that has not been pushed yet, Polinode creates a placeholder node keyed by the external id; when the full entity record later arrives it is merged into place, so the order you push records in doesn't matter.

One Person, One Node

Where the same real person reaches Polinode through more than one source or entity type, Polinode reconciles them into a single node using the identity fields that are unique to a person: email and LinkedIn URL. For example, if a record pushed by a custom source carries the email address of one of your employees, that data binds to the employee's existing node rather than creating a duplicate — the employee's name and attributes are preserved and the custom source's edges simply attach to the existing node. The same applies when one person enters the graph both as an employee (matched by email) and as an external person from a LinkedIn Connections export (matched by LinkedIn URL): the result is one node in your networks, not two.

Managing an Installed Custom Source

Opening Manage on an installed custom source shows its detail view:

  1. Source Key & status: The source's unique key and current status.
  2. Update available: If the underlying template has changed since the source was installed, an Update button appears. Updating refreshes the source's own copy of the template with the latest definitions, while keeping your existing credentials and already-collected data. This is the only way template changes reach a running source — until you choose Update, the source keeps running on the copy it already holds.
  3. Credentials: A searchable, paginated list of the source's credentials, showing when each credential was created and when it was Last Used (both sortable) — making it easy to spot credentials that are no longer in use and can be revoked.
    • For Push credential sources, click New credential to mint a token. The token (a Bearer token) is shown once at creation with a copy-to-clipboard button — store it securely, as it cannot be retrieved again afterwards. You can optionally tick Allow employee entity writes to let that credential create employee entities. Each credential can be Revoked individually, and the list shows the last four characters of each secret for identification.
    • For User email connect sources, credentials are listed by the connecting employee's verified email, and the Admin New credential button is hidden (credentials are issued per employee via the connect flow).
  4. Recent activity: The most recent ingest batches, showing the batch mode and the number of records accepted versus received (and any rejected).
  5. Errors: A collapsible panel listing any recent ingest errors, including the error category and when each occurred.

Queries

You will want to use the Queries section here to produce an interactive network from the stored metadata. To do so simply click the New Query button towards the top right of the screen and then:

  1. Give your query a name
  2. Add the sources that you want to run the query against by clicking the Add Source button and choosing from your active sources, for example Office 365 Email or Microsoft Teams. Any connected Custom Sources also appear in this list under their own labels (for example "LinkedIn Connections"), so you can include them alongside the built-in sources. Each source contributes one or more edge types, and each edge type produces a single edge attribute column with exactly the same name in the resulting network (see Edge attributes below) — for example the Office 365 Directory, Google Workspace Directory and Workday sources contribute Reporting Lines, while Microsoft Teams contributes one edge type per kind of interaction: six from private chats (Teams Chat Direct Messages, Teams Group Chat Messages, Teams Chat Meeting Messages, Teams Chat Mentions, Teams Chat Replies and Teams Chat Reactions) and four from channels (Teams Channel Posts, Teams Channel Mentions, Teams Channel Replies and Teams Channel Reactions). The chat mention, reply and reaction edge types count deliberate acts inside private chats — explicit @-mentions, quoted replies and emoji reactions — and are kept separate from their channel equivalents, whose visibility and meaning differ. Only the edge types that your source's collection settings actually produce are offered — for example a Teams source that is set up to collect channel posts only will not offer the chat edge types (though an edge type already selected in a saved query always remains visible when you edit it). All of a source's edge types are ticked by default; simply uncheck any you don't want. Selecting multiple sources combines them into a single network, and a query can include up to 30 edge types across all of its sources.
  3. Optionally, turn on the Advanced switch on a source to fine-tune each of its edge types with three per-edge-type settings. To make sense of them it helps to know that edge types come in two kinds: interaction edge types (emails, chats, meetings, mentions, reactions and so on) count events over the query's time period, so an edge's weight is how often the pair interacted; relationship edge types (for example Reporting Lines or LinkedIn Connections) are standing facts that either exist or don't, so every edge effectively has a count of 1. That is why relationship rows show a dash for two of the three columns — a minimum interaction count and a strongest-N ranking are meaningless when every edge has the same weight — and only Max Edges applies to them.
    • Min Interactions sets the minimum number of interactions over the time period required to create an edge. Leaving it blank means every interacting pair gets an edge.
    • Max Edges sets the maximum number of edges kept for that edge type; if the maximum is reached, the edges with the fewest interactions are removed until the count is at the maximum. Newly selected edge types start at 100,000, and clearing the field sets the hard maximum of 2,000,000 (there is no unlimited setting). Note that networks above 250,000 edges exceed what the Explore view and metric calculations support — metric calculation will report the network as too large — and networks above 1,048,575 edges additionally cannot be exported to Excel; caps that large are intended for producing networks accessed via the API.
    • Max Edges/Node keeps only each node's strongest N outgoing edges for that edge type, ranked by interaction count — a way of thinning very dense networks down to each person's most significant ties. For undirected edge types such as Meetings, where co-attendance has no direction, it instead keeps each node's strongest N meeting partners. It is applied after Min Interactions and before Max Edges, and leaving it blank applies no per-node limit.
  4. Select a time period, this can be either a trailing time period (e.g. the last 180 days) or an exact time period where you specify a start date and an end date.
  5. Add any filters that you would like. These filters can be either a quick set of filters (which are email addresses and/or domains that you add just for this query) or you can select an existing list or lists to use as a blacklist or whitelist for this query only. If you do the latter then these emails or domains will be either included or excluded from the query. That is to say that it's a convenient way of limiting your query. Each filter also has a direction — In, Out or Both — which controls whether it applies to incoming communication, outgoing communication or both. Note that the direction is ignored for edge types that are undirected by their nature, most notably Meetings: co-attending a meeting is a mutual fact rather than something one person does to another, so there is no incoming or outgoing version of it. For those edge types every filter behaves as Both — a whitelist keeps a pair only when both people are on the list, and a blacklist removes every pair involving anyone on the list.
  6. Optionally, set the Notification Emails for the query. This is who receives the email when the query finishes running, and it defaults to you. You can enter several addresses separated by a comma or semicolon, which is useful for queries that run on a schedule where the person waiting for the network may not be the person who set the query up. Leave the field blank if you don't want any notification to be sent.

Once you've run your query you will see that the query is automatically saved so that you can re-run it again later if you would like — either manually or on a recurring schedule using the Automations module. When you create a query the resulting network will be produced and will be available shortly after you run the query under the Networks tab. When the run completes an email with a link to the new network is sent to the query's Notification Emails. If any edge type reached its Max Edges limit, the email lists the affected edge types and, for each, the interaction count below which the weakest pairs were omitted. Separately, a query as a whole retains at most 2,000,000 edges across all of its edge types; in the unusual case where that overall limit is reached, the email also names the edge types that were truncated or skipped as a result. If a query cannot be completed you will receive an email explaining that, along with suggestions for narrowing it — the most effective of which is usually to split it into several queries covering fewer sources.

Edge attributes

Each edge type you tick produces an edge attribute column with exactly the same name — ticking Emails produces an Emails column, ticking Teams Channel Posts produces a Teams Channel Posts column, and so on. A few edge types that combine more than one kind of interaction add a breakdown alongside their headline column:

  • Emails adds Emails - To, Emails - Cc and Emails - Bcc.
  • Slack Individual Messages adds - DM, - Mention, - Reply and - Reaction.
  • Reporting Lines writes Reporting Line - … columns (singular, as each column describes a single reporting relationship). This family was previously named Direct Reporting; networks built before that rename keep the old column name until they are next re-run.

The only columns containing the word "Total" are rollups. Every network built from at least one interaction edge type carries a Total Interactions column summing all interaction counts on each edge — relationship edge types such as Reporting Lines describe standing facts rather than interactions, so they are not counted (and a network built only from relationship edge types has no totals). In addition, when a query combines multiple sources and one of them contributes two or more interaction edge types, that source also gets its own Total Interactions - <Source Name> rollup (for example Total Interactions - Microsoft Teams). Custom Source edge type labels may not begin with the word "Total" for this reason.

Column renames (July 2026)

Edge attribute columns were previously suffixed with - Total (for example Emails - Total), Teams edge types were grouped differently, and the grand total column was named Total. Networks built before this change keep their old column names until they are next re-run. After a re-run, any saved View that sizes, colours or filters by a renamed column will need that attribute re-selected. The old and new names:

Before Now
Emails - Total Emails (To/Cc/Bcc breakdowns unchanged)
Meetings - Total and Meetings - Invite Meetings (one column)
Office365People - Total Office365People
Slack Individual Messages - Total Slack Individual Messages (breakdowns unchanged)
Slack Channel Posts - Total Slack Channel Posts
Reporting Line - Total Reporting Line
<Custom edge type> - Total <Custom edge type>
Teams Individual Messages - DM Teams Chat Direct Messages
Teams Individual Messages - Mention / - Reply / - Reaction Teams Channel Mentions / Teams Channel Replies / Teams Channel Reactions
Teams Individual Messages - Total (no direct equivalent — see the Teams rollup)
Teams Chat Mentions and Reactions - Total Teams Chat Mentions + Teams Chat Reactions (two columns)
Teams Chat Replies - Total Teams Chat Replies
Teams Group Chat Messages - Total Teams Group Chat Messages
Teams Meeting Chat Messages - Total Teams Chat Meeting Messages
Teams Channel Posts - Total Teams Channel Posts
Total Total Interactions

Saved queries that selected the former Teams Individual Messages or Teams Chat Mentions and Reactions edge types were automatically updated to the equivalent new edge types, keeping any Min Interactions / Max Edges settings.

The networks produced from your queries also carry through additional attributes from your sources. Attributes from standing (ongoing) relationships are surfaced as edge attributes on the resulting network, and where a source provides date-based attributes Polinode will also derive convenient elapsed-time edge attributes from them. Where a source includes people outside your organization (for example external contacts from a CRM or LinkedIn source), their attributes are surfaced on the corresponding network nodes.

Lists

The last tab is where you upload your lists, that is an Excel file that contains a set of domains and/or email addresses. It's these lists that you can then use as either Master Whitelists, Master Blacklists or to link to when setting up a query.

Settings

Towards the right of the screen you will find a button to access Settings for the Passive Data integrations. Some of these settings are configured by Polinode on setup and some can be controlled by an Admin user in your organization. The configurable settings are detailed in the Employee Attributes Source, Master Lists, Data Export and Error Alerts sections below whereas the non-configurable settings are covered in the Other Settings section.

Employee Attributes Source

Employee attributes — a person's display name, job title, department, timezone and so on — can be supplied by more than one of your connected sources. This section lets an Admin user choose which connected source supplies them, using two pickers:

  1. Attribute source: Supplies all non-timezone employee attributes (display name, job title, department and the like). This includes employment status — the attribute source is what marks employees active or terminated, and employees it marks terminated are excluded from passive data collection across all sources.
  2. Timezone source: Supplies the employee timezone only. It is kept separate because timezone often comes from a different part of a provider than the other attributes.

Each picker offers Automatic (the default) or a specific connected source, and custom sources can be chosen as well:

  • Automatic uses your highest-priority connected source and follows that source as your connections change. For the attribute source the priority order is Workday, then Office 365 Directory, then Google Workspace Directory, then Slack; for the timezone source it is Office 365 Directory, then Google Workspace Calendar, then Slack (Workday does not supply timezones). When Automatic is selected a caption shows which source is currently in use.
  • Choosing a specific source overrides the automatic priority. Each source fills only the attributes it can provide; anything it doesn't supply is left blank.

If no source that can supply attributes (or timezones) is connected yet, the relevant picker is replaced by an information note explaining which sources to connect; until then those values are left blank.

Reporting Lines Source

Manager reporting lines (the reports-to relationships behind the Reporting Lines edge type in queries) are supplied by a single source, chosen by an Admin user with the Reporting lines source picker:

  1. Automatic (the default) uses your highest-priority connected source that can supply reporting lines, in this order: Workday, then Office 365 Directory, then Google Workspace Directory — and follows that source as your connections change.
  2. None turns reporting-line collection off.
  3. Choosing a specific source makes that source supply reporting lines regardless of the automatic priority.

Only one source supplies reporting lines at a time. When you switch sources (or choose None), the previously selected source removes its old reporting lines on its next daily run, so the change fully takes effect within a day.

Master Lists

These are settings that an admin user for your account can control and change.

  1. Master Whitelist: Under the Lists tab (see below) you can upload a series of lists that contain either email domains, addresses or both. Here you can specify one of these lists as a Master Whitelist, which means that when Polinode saves metadata for your organization it will only save the metadata if the associated email address matches either an email address or domain in the Master Whitelist. If no whitelist is specified then there will be no such restriction. This is typically used to limit the communication data that is saved to internal communication only. Note that if this list is edited it will apply going forward only and not historically.
  2. Master Blacklist: The Master Blacklist is similar to the Master Whitelist except that it operates to exclude (rather than include) specific domains or email addresses from the data collection.

Data Export

In this section you may optionally configure an S3 bucket in your own AWS account for Polinode to export the raw metadata it has collected for further analysis. This includes timezone adjusted data such as the day of the week and hour of the day that individual interactions occurred at.

Setting up your bucket

Your bucket must meet the following requirements:

  1. Object Ownership must be set to Bucket owner enforced. This has been the AWS default for all buckets created since April 2023, so no action is normally needed. With this setting your account automatically owns every object Polinode writes. Buckets with ACLs enabled are not supported — if your bucket is older and still has ACLs enabled, switch Object Ownership to Bucket owner enforced (a one-click change under the bucket's Permissions tab).
  2. The bucket may be in any AWS region.
  3. We recommend adding a lifecycle rule that aborts incomplete multipart uploads after 7 days (AbortIncompleteMultipartUpload). This cleans up any partial upload left behind if an export is interrupted.
  4. If your bucket has versioning enabled, note that connection tests overwrite a small test file each time, so noncurrent versions of that file will accumulate subject to your own lifecycle rules.

To grant Polinode write access, attach the following bucket policy (under the bucket's Permissions tab, Bucket policy), replacing YOUR-BUCKET-NAME with your bucket's name. The only permission Polinode needs is s3:PutObject:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PolinodeWriteAccess",
            "Effect": "Allow",
            "Principal": { "AWS": "arn:aws:iam::534609415919:root" },
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
        }
    ]
}

Configuring and running exports

  1. Bucket Name: The name of the S3 bucket you have granted Polinode permission to write to, as above.
  2. Path: The path in this bucket where Polinode should export your data.

Once you have configured the above, click Update Export Settings to save. You can then use:

  1. Send Test File: Verifies Polinode's write access by writing a small self-describing file (polinode-connection-test.txt) to your configured path. The file is safe to delete and is overwritten on each test.
  2. Export Data: Opens a dialog to start an export. You can choose a time period (all data, a trailing window, or exact dates) that applies to the interactions and meetings files — rosters and standing relationships are always exported in full. You can also choose whether to receive a completion email and at which address. The time period choice (other than exact dates) and the email settings are saved and reused by scheduled exports.
  3. Run History: Shows recent export runs — when each ran, whether it was manual or scheduled, its status, coverage, row counts and the run folder name, plus the error message for any failed run.

Export format

Each export run writes a set of gzipped CSV files into its own folder under your configured path: <path>/v2/<run id>/. A manifest.json file is written last, after every data file has fully uploaded. A run folder is complete only once it contains manifest.json — your import process should ignore folders without one. The manifest lists each file with its row count and the time window it covers, and the names it lists are the exact object names in the folder.

Every data file is gzip-compressed and named accordingly, ending in .csv.gz. Decompress each file before reading it — most tools do this automatically (gunzip on the command line, or a gzip-aware CSV reader such as pandas' read_csv, which detects the compression from the extension).

The files are:

  1. entities.csv.gz: The canonical identity table — every entity of every kind (employees, external people, companies, channels, channel groups and opportunities), including entities that have been orphaned or deleted. Columns include entityId, kind, displayName, email, domain, explicit orphaned and deleted lifecycle columns, and a record column containing the entity's full remaining data as JSON. Because lifecycle columns are explicit, your import process should never infer deletion from a row's absence.
  2. employees.csv.gz: The employee roster — one row per current (non-orphaned, non-deleted) employee, keyed by entityId, with the flattened HR attribute columns plus a record JSON column.
  3. interactions.csv.gz: One row per interaction event (emails, chat messages, channel posts, calls and so on — everything except meetings), with the raw interaction type, both endpoints (sourceEntityId/targetEntityId with denormalized emails, names and kinds), timezone-adjusted time-of-day fields, and an attributes JSON column for any per-event extras. New interaction types your sources produce in the future appear here automatically.
  4. meetings.csv.gz: One row per meeting, with the organiser and an attendees column containing a single JSON array of {entityId, email, status} objects, plus a record JSON column for the remaining meeting fields.
  5. standing-relationships.csv.gz: One row per standing (ongoing) relationship of every type, such as reporting lines and LinkedIn connections, with observedFrom/observedUntil observation dates.

Two rules matter when joining these files:

  1. entityId is the only join key. It is the stable, canonical identifier for a person or other entity and appears on every endpoint in every file. Email addresses are denormalized labels captured at export time — they can be blank and must not be treated as identities.
  2. JSON columns (record, attendees, ownedBy, attributes) contain standard JSON with dates as ISO-8601 strings and ids as hex strings, escaped like any other CSV cell.

One caveat: when two entities are merged, the losing entityId is deleted and simply stops appearing in later snapshots; historical rows that referenced it will no longer join.

Scheduled exports

You can schedule recurring exports with an automation using the Export passive data to S3 action (see the Automations documentation). Scheduled exports may run at most weekly and behave as follows:

  1. interactions.csv.gz is an incremental feed. Each scheduled run exports only the interaction rows added since the previous run, so the sequence of scheduled runs forms a historical log. Each run covers data added up to approximately 15 minutes before the run starts — this safety margin ensures no data is skipped between runs, at the cost of the newest few minutes appearing in the next run instead. The first scheduled run seeds the feed using your saved time period.
  2. All other files are full snapshots each run. Rosters and standing relationships are always complete; meetings.csv.gz follows your saved time period. Your import process should replace each snapshot wholesale — the latest file wins. The interactions log is never retro-corrected: snapshot files are the truth for current state.
  3. Late-arriving history: if older data is backfilled into Polinode between runs, it appears in the next incremental run with its original (old) dates.
  4. Duplicates only after failures: if a run fails, the next run re-exports the same range, so rows can appear twice across run folders. De-duplicate interactions on (interactionType, sourceId, sourceEntityId, targetEntityId) and meetings on sourceId.
  5. Changing the bucket or path does not restart the feed — the incremental cursor carries over. If you need a fresh full export to a new destination, please contact support.

When an export completes, a summary email is sent to the configured notification address (if enabled) listing the run folder, per-file row counts and coverage.

Polinode Datashield

Polinode Datashield is a server that you host and that Polinode routes passive data requests through, so that data is processed within your own environment. Datashield is enabled for your organization by Polinode; once it is enabled, an Admin user in your organization owns the Datashield URL — the address of your Datashield deployment.

You are prompted for the Datashield URL the first time you connect a Datashield-capable source (see below), and the same URL is then reused for every Datashield source. You can also view and change it in this Settings section afterwards. To save a change, enter the new address and click Update Polinode Datashield URL.

There is a Test Connection button which runs a read-only diagnostic against your configured Datashield deployment. It validates the configuration and performs a per-service health check for each Datashield-routed service (e.g. Microsoft Graph, Slack, etc.). A modal opens with an overall pass/fail status, any errors or warnings, a per-service status list and a collapsible raw report. This is useful for quickly confirming connectivity after a Datashield URL change or when investigating a suspected Datashield-related issue. You can test a URL you have typed in but not yet saved — the results will note that the URL has not been saved and remind you to click Update Polinode Datashield URL to keep it.

Whether an individual source routes its traffic through Datashield is chosen at connect time. For Datashield-capable sources (Polinode's Microsoft, Google and Workday integrations), the provider connect dialog shows a Use Polinode Datashield toggle at the top, on by default when your organization has Datashield enabled. Turn it off to connect that source directly instead. The very first time you connect a Datashield source — before any URL is saved — a Polinode Datashield URL field and a Test Connection button appear inline in the same dialog so you can supply the address once. For Workday, routing through Datashield also means the ISU credentials are configured only in your Datashield deployment — Polinode never receives them; your IT team sets this up following the Workday setup guide included in the Datashield repository documentation, or with help from your Polinode contact. Slack and custom sources do not route through Datashield.

Error Alerts

Each of your connected sources imports data on a daily schedule. If one of those imports fails — for example the provider returns an error, or credentials stop working — the source is marked In Error on the Sources tab with a short description of what went wrong. This section lets an Admin user nominate people to be emailed when that happens, so a failure does not go unnoticed until someone next opens the page.

Enter one or more addresses in the Error Alert Emails field, separated by a comma or a semicolon, and click Update Error Alerts. Leave the field blank to turn these alerts off.

You are emailed when a source starts failing and again when it recovers — not once for every retry. A source that fails several days in a row therefore produces one alert, not one per day, and a second email arrives when the next import succeeds. Each alert names the source and includes the same error description shown on the source card. Alerts cover all of your sources, both built-in and custom.

Other Settings

These are settings that can be set and changed via your Polinode Account Manager.

  1. Max Email Recipients: This is a setting controlled by your Account Manager and may be changed on request. It determines the maximum nunber of email recipients on an email after which the email is excluded for metadata analysis. The default is 100.
  2. Max Meeting Recipients: This setting is similar to Max Email Recipients but for Meeting Recipients. The default is 50.
  3. Number of People: This is also a settign controlled by your Account Manager and which can be changed on request. It relates to the Office 365 People API, i.e. it is the Top X people that are collected for each individual.
  4. Employees Connected: The number of unique employees currently connected to your organization across all passive data sources, shown against your Max Employees limit (e.g. "110 of 250"). The Max Employees limit is the maximum number of employees for which metadata can be collected and is controlled by your Account Manager. If the number of connected employees ever exceeds the limit, a warning is shown here — please contact support if you see it.
  5. Retention Period: Data is stored on a rolling basis, i.e. each day the last day of data is automatically dropped where the last day is determined by this retention period. This setting is controlled by your Account Manager.
  6. Initial Retrieval Period: This is the initial period that Polinode will go back when retrieving historical data when the integrations are first setup.
  7. Daily Backfill Step: This setting is only shown when it has been enabled by your Account Manager. When enabled, historical data beyond the Initial Retrieval Period is imported gradually — this many additional days of history with each daily run — until the full Retention Period is covered. This spreads the load of a large historical import over time rather than retrieving it all at once.

← Social Data →