Skip to main content

Map API Fields to NIM Resources

Data model · Resources

Choose the API fields NIM should collect and map, then describe their shape in a way that stays stable as the connector evolves.

What resources becomeDirect link to What resources become

Every entry in a table's resources object becomes a NIM column or a path to columns. Define the fields that your workflows need—not every field returned by the API.

"resources": {
  "id": "string*",
  "displayName": "string*",
  "active": "boolean",
  "hireDate": "date"
}

The value describes the field type. The * marks a field for collection by default when the system is first added to NIM.

Choose the right shapeDirect link to Choose the right shape

API response shapeResource definitionResult in NIM
A scalar value"email": "string"One column.
A nested object"name": { "given": "string" }A flattened path such as name_given.
An array of objects"emails": [{ "address": "string" }]A child table for the repeated records.

Nested objectsDirect link to Nested objects

Use an object for a single nested value. NIM creates a column name from the path.

"resources": {
  "name": {
    "given": "string*",
    "family": "string*"
  }
}

This produces name_given and name_family columns.

Child tablesDirect link to Child tables

Use an array when the API returns repeated objects, such as emails, phone numbers, or assignments. Child tables can exist directly under resources.

"resources": {
  "id": "string*",
  "emails": [{
    "address": "string*",
    "type": "string",
    "primary": "boolean"
  }]
}
Start simple

Add child tables only when a collection or mapping needs repeated values. They increase the data model and need realistic collection tests.

Type specifiersDirect link to Type specifiers

Use these type names for scalar resources: string, number, boolean, date, and datetime. NIM currently does not use the type to coerce data during system setup, but declaring the intended type makes the connector readable and protects future maintenance.

SyntaxMeaning
"id": "string*"String selected for collection by default.
"active": "boolean"Boolean field, not selected by default.
"startDate": "date"Date field.
"updated": "datetime"Date-and-time field.

Avoid column-name collisionsDirect link to Avoid column-name collisions

NIM flattens resource paths. If two nested branches would create the same column name, prefix the type with _: to give that field an alternate NIM name.

"addresses": {
  "mailing": { "city": "_:string", "street": "_:string" },
  "physical": { "city": "_:string", "street": "_:string" }
}

This preserves separate flattened names such as addresses_mailing_city and addresses_physical_city.

Manage array values through operationsDirect link to Manage array values through operations

An advanced resource object uses _nim_mode_, config, and, for update modes, handler. config describes the resource's collected shape.

_nim_mode_Behavior
defaultWrap an ordinary resource definition in config.
array_element_updateAdd or remove individual array values through dedicated operations.
array_updateMerge desired elements with the current destination array and send the full merged array through one operation.

To add and remove aliases through separate operations, configure an element-update handler as follows. See Google Workspace for a connector example.

"aliases": {
  "_nim_mode_": "array_element_update",
  "config": ["string*"],
  "handler": {
    "crud_object": "users_aliases",
    "add": {
      "operation": "user_alias_create",
      "attributes": { "id": "id", "alias": "_nim_element_value_" }
    },
    "remove": {
      "operation": "user_alias_delete",
      "attributes": { "id": "id", "alias": "_nim_element_value_" }
    }
  }
}

For element updates, handler.add and handler.remove each require operation and attributes. Attribute keys name the operation inputs; string values identify the source fields, and _nim_element_value_ supplies the current array element. Set handler.crud_object to the handler table. This property is deprecated but remains required for array_element_update validation.

For array_update, configure handler.operation and handler.attributes. The attributes map operation inputs to source fields in functionNameValues or resultObject; the operation receives the fully merged array. Use this mode when an API requires the complete array for an update, such as a custom-field collection. Test both additions and removals against existing destination values before enabling either update mode.

Validate the resource modelDirect link to Validate the resource model

  • Include a stable identifier and mark it for default collection.
  • Include the attributes required by mappings, filters, and lookups.
  • Keep names stable once a NIM mapping uses them.
  • Test nested objects and child arrays with real API responses.
  • Define write allowances in the operation—not by assuming all collected resources are writable.

Next: choose the table key, then define its operations.

Last updated on