# GraphQL API Authentication Source: https://docs.sensorup.com/api/graphql/authentication Learn how to authenticate with the SensorUp GraphQL API using sessions, API keys, and AWS credentials. # Authentication The SensorUp GraphQL API supports multiple authentication methods depending on your use case and environment. ## Authentication Methods | Method | Use Case | Lifetime | MFA Support | | - | - | - | - | | **Session-based** | Interactive web applications | 7-30 days idle, 30-365 days max (varies by client) | Yes | | **API Keys** | Machine-to-machine, integrations | 60 days idle, 365 days max | No | | **Federated Sign-in** | SSO integration | Same as session-based | Via SSO provider | All authentication methods use the same session ID mechanism - either via the `sensorup_sessionid` cookie (browser) or `x-sensorup-sessionid` header (API clients). ## Session-Based Authentication Session-based authentication is the primary method for interactive applications where users log in with username and password. ### Sign In ```graphql theme={null} mutation SignIn($input: AuthSignInInput!) { signIn(input: $input) { session { username authenticated expiresAt expiresAtHard userGroup challengeName } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "loginUsername": "user@example.com", "password": "your-password", "clientApplicationType": "EXPLORER" } } ``` ### Session Response ```json theme={null} { "data": { "signIn": { "session": { "username": "user@example.com", "authenticated": true, "expiresAt": "2025-11-05T18:00:00Z", "expiresAtHard": "2025-11-06T10:00:00Z", "userGroup": "your-tenant-id", "challengeName": null }, "correlationId": "abc-123", "errors": [] } } } ``` ### Checking Current Session ```graphql theme={null} query GetSession { session { username authenticated expiresAt userGroup lastAuthenticatedAt } } ``` ### Sign Out ```graphql theme={null} mutation SignOut { signOut { session { authenticated } correlationId errors { message type } } } ``` ### Using Your Session After successful sign-in, your session ID is used to authenticate subsequent API requests. There are two methods: #### 1. Cookie Authentication (Browser/Web) When you sign in through a web browser, the `sensorup_sessionid` cookie is automatically set and sent with each request: ``` Cookie: sensorup_sessionid=YOUR_SESSION_ID ``` This happens automatically - you don't need to manually set this cookie in browser applications. #### 2. Header Authentication (Machine-to-Machine) For API clients, mobile apps, and integrations, pass the session ID in the `x-sensorup-sessionid` header: ```bash theme={null} curl -X POST https://customer-demo.sensorup.com/api/graphql \ -H "Content-Type: application/json" \ -H "x-sensorup-sessionid: YOUR_SESSION_ID" \ -d '{"query":"{ session { username authenticated } }"}' ``` **Using with HTTP clients:** ```javascript theme={null} // JavaScript/Node.js fetch('https://customer-demo.sensorup.com/api/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-sensorup-sessionid': sessionId }, body: JSON.stringify({ query: '{ session { username } }' }) }) ``` ```python theme={null} # Python import requests response = requests.post( 'https://customer-demo.sensorup.com/api/graphql', headers={ 'Content-Type': 'application/json', 'x-sensorup-sessionid': session_id }, json={'query': '{ session { username } }'} ) ``` ## Multi-Factor Authentication (MFA) When MFA is required, the sign-in mutation returns a `challengeName`: ### MFA Challenge Response ```json theme={null} { "session": { "username": "user@example.com", "authenticated": false, "challengeName": "SMS_MFA", "challengeParam": {} } } ``` ### Challenge Types | Challenge | Description | | - | - | | `SMS_MFA` | SMS-based one-time code | | `SOFTWARE_TOKEN_MFA` | TOTP authenticator app | | `MFA_SETUP` | MFA setup required | | `NEW_PASSWORD_REQUIRED` | Password reset required | ### Completing MFA Challenge ```graphql theme={null} mutation ConfirmSignIn($input: AuthConfirmSignInInput!) { confirmSignIn(input: $input) { session { username authenticated expiresAt } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "code": "123456", "mfaType": "SMS_MFA" } } ``` ## API Key Authentication API keys are designed for machine-to-machine communication and integration scenarios. API keys generate sessions just like user logins, but with longer lifetimes. ### Creating an API Key ```graphql theme={null} mutation CreateAPIKey($input: AuthCreateAPIKeyInput!) { createAPIKey(input: $input) { apiKey { apiKeyId apiKeySessionId username authenticated expiresAt userGroup } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "apiKeyId": "my-integration-key", "userGroup": "your-tenant-id" } } ``` The response includes an `apiKeySessionId` which is the session ID you'll use for authentication. API keys provide full access to the API with the same permissions as the user who created them. Store them securely and rotate them regularly. ### Using API Keys Use the API key session ID in the `x-sensorup-sessionid` header (same as regular sessions): ```bash theme={null} curl -X POST https://customer-demo.sensorup.com/api/graphql \ -H "Content-Type: application/json" \ -H "x-sensorup-sessionid: YOUR_API_KEY_SESSION_ID" \ -d '{"query":"{ session { username } }"}' ``` **Integration Example:** ```javascript theme={null} // Store the API key session ID securely const apiKeySessionId = process.env.SENSORUP_API_KEY_SESSION_ID // Use in requests const response = await fetch('https://customer-demo.sensorup.com/api/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-sensorup-sessionid': apiKeySessionId }, body: JSON.stringify({ query: '{ session { username } }' }) }) ``` ## AWS Credentials For accessing AWS services (S3, etc.), you can obtain temporary AWS credentials: ### Getting AWS Credentials ```graphql theme={null} query GetCredentials($group: String) { credentials(group: $group) { accessKeyId secretAccessKey sessionToken expiration } } ``` **Response:** ```json theme={null} { "data": { "credentials": { "accessKeyId": "ASIA...", "secretAccessKey": "...", "sessionToken": "...", "expiration": "2025-11-05T18:00:00Z" } } } ``` ### Using AWS Credentials ```javascript theme={null} import AWS from 'aws-sdk' // Configure AWS SDK with credentials from GraphQL AWS.config.credentials = new AWS.Credentials({ accessKeyId: credentials.accessKeyId, secretAccessKey: credentials.secretAccessKey, sessionToken: credentials.sessionToken }) // Use AWS services const s3 = new AWS.S3() ``` ## Federated Sign-In (SSO) For organizations using SSO, you can authenticate with Cognito tokens: ```graphql theme={null} mutation FederatedSignIn($input: AuthFederatedSignInInput!) { federatedSignIn(input: $input) { session { username authenticated expiresAt userGroup } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "cognitoIdToken": "your-id-token", "clientApplicationType": "EXPLORER" } } ``` SSO configuration is tenant-specific. Contact your SensorUp account team for SSO setup and configuration. ## Session Management ### Session Expiration Sessions have two expiration times: * **Soft Expiry (Idle Timeout)**: Session extends with activity up to this limit * **Hard Expiry (Maximum Lifetime)**: Absolute maximum session duration - requires re-authentication after this time Session lifetimes vary by client application type: | Client Application Type | Hard Expiry (Max Lifetime) | Soft Expiry (Idle Timeout) | | - | - | - | | **Explorer** (Web) | 30 days | 7 days | | **SensorHub Android** | 365 days | 60 days | | **SensorHub iOS** | 365 days | 60 days | | **API Key** | 365 days | 60 days | **How it works:** * If you're actively using the API, your session stays valid until the hard expiry time * If you're inactive for longer than the soft expiry (idle timeout), the session expires * After hard expiry, you must sign in again regardless of activity * The `expiresAt` field in the session response reflects the current soft expiry time * The `expiresAtHard` field shows the absolute maximum session lifetime ### Switching User Groups If your user has access to multiple tenant groups: ```graphql theme={null} mutation SetUserGroup($input: AuthSetSessionUserGroupInput!) { setSessionUserGroup(input: $input) { session { userGroup } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "userGroup": "different-tenant-id" } } ``` ### Re-authentication For sensitive operations, you may need to re-authenticate: ```graphql theme={null} mutation Reauthenticate($input: ReauthenticationInput!) { reauthenticate(input: $input) { session { username authenticated lastAuthenticatedAt } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "password": "your-password" } } ``` ## Device Management Track and manage authenticated devices: ### Listing Devices ```graphql theme={null} query GetUserDevices($userId: ID!) { user(id: $userId) { devices { deviceKey name remembered createdAt lastSignedInAt lastIpAddress } } } ``` ### Forgetting Devices ```graphql theme={null} mutation ForgetDevices($input: AuthForgetSpecificDevicesInput!) { forgetDevices(input: $input) { session { username } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "deviceKeys": ["device-key-1", "device-key-2"] } } ``` ## Password Management ### Forgot Password ```graphql theme={null} mutation ForgotPassword($input: AuthForgotPasswordInput!) { forgotPassword(input: $input) { correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "loginUsername": "user@example.com" } } ``` ### Reset Password ```graphql theme={null} mutation ForgotPasswordSubmit($input: AuthForgotPasswordSubmitInput!) { forgotPasswordSubmit(input: $input) { session { username authenticated } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "loginUsername": "user@example.com", "confirmationCode": "123456", "password": "new-password" } } ``` ## Authentication Configuration Query authentication configuration for your environment: ```graphql theme={null} query GetAuthConfig { config { auth { loginEnabled ssoEnabled ssoUrl } } } ``` ## Best Practices 1. **Use sessions for interactive applications**: Session-based auth with MFA provides the best security for user-facing applications 2. **Use API keys for integrations**: Machine-to-machine communication should use API keys with appropriate scoping 3. **Rotate credentials regularly**: Implement key rotation policies for long-lived API keys 4. **Handle session expiration gracefully**: Check `expiresAt` and refresh or re-authenticate before expiration 5. **Store credentials securely**: Never commit credentials to version control; use environment variables or secret management systems 6. **Monitor authentication events**: Track authentication failures and unusual patterns ## Next Steps * **[Quickstart Guide](./quickstart)** - Make your first authenticated query * **[Common Patterns](./common-patterns)** - Learn about pagination and filtering * **[Domain Guides](./guides/cam-assets)** - Explore specific API capabilities # Common Patterns Source: https://docs.sensorup.com/api/graphql/common-patterns Essential patterns for working with the SensorUp GraphQL API - pagination, filtering, error handling, and GeoJSON. # Common Patterns This guide covers common patterns you'll use throughout the SensorUp GraphQL API. ## Pagination The API uses **Relay-style cursor-based pagination** for all list queries. This provides consistent forward and backward pagination with cursor stability. ### Connection Structure ```graphql theme={null} type Connection { edges: [Edge] pageInfo: PageInfo! } type Edge { node: NodeType cursor: String } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } ``` ### Forward Pagination ```graphql theme={null} query GetAssets($first: Int!, $after: String) { assetProfiles { byId(profile: "your-profile") { assets(first: $first, after: $after) { edges { node { id displayName } cursor } pageInfo { hasNextPage endCursor } } } } } ``` **First page:** ```json theme={null} { "first": 20 } ``` **Next page:** ```json theme={null} { "first": 20, "after": "cursor-from-endCursor" } ``` ### Backward Pagination ```graphql theme={null} query GetAssets($last: Int!, $before: String) { assetProfiles { byId(profile: "your-profile") { assets(last: $last, before: $before) { edges { node { id displayName } } pageInfo { hasPreviousPage startCursor } } } } } ``` ### Pagination Best Practices 1. **Use reasonable page sizes**: 10-100 items per page depending on data size 2. **Store cursors, not offsets**: Cursors remain valid even when data changes 3. **Check hasNextPage**: Don't assume there's always a next page 4. **Handle missing cursors**: Some connections may not return cursors for every edge ## Filtering Most list queries support filtering through typed input objects. ### Time-Based Filtering ```graphql theme={null} query GetRecentAssets($filter: AssetFilter!) { assetProfiles { byId(profile: "your-profile") { assets(first: 20, filter: $filter) { edges { node { id displayName modifiedAt } } } } } } ``` **Variables:** ```json theme={null} { "filter": { "modifiedAfter": "2025-11-01T00:00:00Z" } } ``` ### Property-Based Filtering Some queries allow filtering by specific properties: ```graphql theme={null} query FilteredObservations( $startTime: DateTime, $endTime: DateTime, $properties: [String!] ) { assetProfiles { byId(profile: "your-profile") { upQueryObservations( startTime: $startTime, endTime: $endTime, properties: $properties ) } } } ``` **Variables:** ```json theme={null} { "startTime": "2025-11-01T00:00:00Z", "endTime": "2025-11-05T00:00:00Z", "properties": ["temperature", "pressure"] } ``` ## Error Handling The API uses two error patterns: GraphQL-level errors and mutation-level errors. ### GraphQL Errors GraphQL errors appear in the `errors` array at the top level: ```json theme={null} { "errors": [ { "message": "Cannot query field 'invalidField' on type 'Asset'", "locations": [{ "line": 3, "column": 5 }], "path": ["assetProfiles", "byId", "invalidField"] } ], "data": null } ``` **Common GraphQL error types:** * **Validation errors**: Invalid query syntax or schema violations * **Authentication errors**: Missing or invalid credentials * **Authorization errors**: Insufficient permissions * **Internal errors**: Server-side issues ### Mutation Errors Mutations return errors in their result type using the `MutationError` interface: ```graphql theme={null} interface MutationError { message: String! type: String! } ``` **Example mutation with errors:** ```graphql theme={null} mutation CreateAssetFilter($input: CreateAssetFilterInput!) { createAssetFilter(input: $input) { assetFilter { id displayName } correlationId errors { message type } } } ``` **Response with validation error:** ```json theme={null} { "data": { "createAssetFilter": { "assetFilter": null, "correlationId": "abc-123", "errors": [ { "message": "Display name is required", "type": "VALIDATION_ERROR" } ] } } } ``` ### Error Handling Pattern ```javascript theme={null} const result = await executeQuery(mutation, variables) // Check for GraphQL-level errors if (result.errors) { console.error('GraphQL errors:', result.errors) return } // Check for mutation-level errors const { assetFilter, errors } = result.data.createAssetFilter if (errors && errors.length > 0) { console.error('Mutation errors:', errors) return } // Success console.log('Created asset filter:', assetFilter) ``` ## GeoJSON Support The API has comprehensive GeoJSON support for geospatial data. ### GeoJSON Types ```graphql theme={null} enum GeoJSONType { Point MultiPoint LineString MultiLineString Polygon MultiPolygon GeometryCollection Feature FeatureCollection } ``` ### Querying Geometry ```graphql theme={null} query GetAssetGeometry($profileId: ID!, $assetId: ID!) { assetProfiles { byId(profile: $profileId) { assetById(id: $assetId) { id displayName geometry { type coordinates bbox } geoJSONFeature } } } } ``` **Response:** ```json theme={null} { "data": { "assetProfiles": { "byId": { "assetById": { "id": "asset-123", "displayName": "Well Site A", "geometry": { "type": "Point", "coordinates": [-114.0719, 51.0447], "bbox": null }, "geoJSONFeature": { "type": "Feature", "geometry": { "type": "Point", "coordinates": [-114.0719, 51.0447] }, "properties": { "name": "Well Site A" }, "id": "asset-123" } } } } } } ``` ### GeoJSON Input ```graphql theme={null} input GeoJSONGeometryInput { type: GeoJSONType! coordinates: GeoJSONCoordinates bbox: [Float] } ``` **Example usage in mutations:** ```json theme={null} { "geometry": { "type": "Point", "coordinates": [-114.0719, 51.0447] } } ``` ### Coordinate Systems * All coordinates use **WGS84** (EPSG:4326) * Coordinate order: `[longitude, latitude]` (GeoJSON standard) * Elevations can be included as third coordinate: `[lon, lat, elevation]` ## Audit Trails Many types include audit information for tracking changes. ### Audit Type ```graphql theme={null} type Audit { createdTime: DateTime! updatedTime: DateTime! createdBy: UserReference updatedBy: UserReference } ``` ### Querying Audit Information ```graphql theme={null} query GetIssueAudit($issueId: ID!) { issues { byId(id: $issueId) { id displayName audit { createdTime updatedTime createdBy { userId } updatedBy { userId } } } } } ``` **Response:** ```json theme={null} { "data": { "issues": { "byId": { "id": "issue-123", "displayName": "Equipment Failure", "audit": { "createdTime": "2025-11-01T10:00:00Z", "updatedTime": "2025-11-03T14:30:00Z", "createdBy": { "userId": "user-1" }, "updatedBy": { "userId": "user-2" } } } } } } ``` ## Entity References Apollo Federation enables cross-subgraph entity resolution. ### User References ```graphql theme={null} type UserReference @key(fields: "userId") { userId: ID! } ``` **Query user references:** ```graphql theme={null} query GetUserDetails { issues { byId(id: "issue-123") { audit { createdBy { userId # Additional user fields resolved by su-user subgraph } } } } } ``` ### Asset References ```graphql theme={null} type AssetReference @key(fields: "profile assetId") { profile: ID assetId: ID! asset: Asset } ``` ## DateTime Handling All timestamps use ISO-8601 format in UTC. ### DateTime Format ``` 2025-11-05T14:30:00Z 2025-11-05T14:30:00.123Z (with milliseconds) ``` ### Querying with DateTime ```graphql theme={null} query GetRecentData($startTime: DateTime!, $endTime: DateTime!) { assetProfiles { byId(profile: "your-profile") { upQueryObservations( startTime: $startTime, endTime: $endTime ) } } } ``` **Variables:** ```json theme={null} { "startTime": "2025-11-01T00:00:00Z", "endTime": "2025-11-05T23:59:59Z" } ``` ### Relative Time Queries Some fields support relative time strings: ```graphql theme={null} query GetLiveData { assetProfiles { byId(profile: "your-profile") { # Historical: "7 days ago" to "now" upQuery(startTime: "7 days ago", endTime: "now") # Live data: "now" upQuery(startTime: "now") } } } ``` ## JSONObject Type The `JSONObject` scalar represents arbitrary JSON data. ### Querying JSON Properties ```graphql theme={null} query GetAssetProperties($profileId: ID!, $assetId: ID!) { assetProfiles { byId(profile: $profileId) { assetById(id: $assetId) { id properties observation } } } } ``` **Response:** ```json theme={null} { "data": { "assetProfiles": { "byId": { "assetById": { "id": "asset-123", "properties": { "name": "Well Site A", "operator": "Company XYZ", "capacity": 1000 }, "observation": { "phenomenonTime": "2025-11-05T14:00:00Z", "result": { "pressure": 150.5, "temperature": 22.3 } } } } } } } ``` ### Filtering JSON Properties ```graphql theme={null} query GetSelectedProperties( $profileId: ID!, $assetId: ID!, $properties: [String!] ) { assetProfiles { byId(profile: $profileId) { assetById(id: $assetId) { id properties(only: $properties) } } } } ``` **Variables:** ```json theme={null} { "profileId": "wells", "assetId": "well-123", "properties": ["name", "operator"] } ``` ## Correlation IDs All mutations return a `correlationId` for tracking and debugging. ```graphql theme={null} mutation CreateAssetFilter($input: CreateAssetFilterInput!, $correlationId: String) { createAssetFilter(input: $input, correlationId: $correlationId) { assetFilter { id } correlationId errors { message } } } ``` **Providing your own correlation ID:** ```json theme={null} { "input": { ... }, "correlationId": "my-unique-id-123" } ``` Use correlation IDs for: * Request tracking across systems * Debugging with support teams * Audit logging * Idempotency (some mutations) ## Best Practices 1. **Request only needed fields**: GraphQL allows precise field selection - use it to reduce payload size 2. **Use fragments for reusability**: Define reusable fragments for common field sets 3. **Batch related queries**: Use GraphQL's ability to query multiple resources in one request 4. **Handle errors at both levels**: Check for GraphQL errors AND mutation errors 5. **Store cursors for pagination**: Cursors remain stable across data changes 6. **Use correlation IDs**: Include them for better debugging and tracking 7. **Respect rate limits**: Implement exponential backoff for retries 8. **Cache appropriately**: Consider caching strategies based on data volatility ## Next Steps * **[Domain Guides](./guides/cam-assets)** - Explore specific use cases * **[Subgraph Reference](./subgraphs/assets)** - Detailed schema documentation * **[Federation Concepts](./federation)** - Understanding entity composition * **[Performance](./performance)** - Optimization and best practices # Apollo Federation Concepts Source: https://docs.sensorup.com/api/graphql/federation Understanding how the SensorUp GraphQL API uses Apollo Federation to compose multiple subgraphs into a unified API. # Apollo Federation Concepts The SensorUp GraphQL API is built on **Apollo Federation v2.3**, which enables multiple independent GraphQL services (subgraphs) to be composed into a single, unified graph. ## What is Apollo Federation? Apollo Federation is an architecture for building distributed GraphQL APIs. Instead of one monolithic GraphQL server, Federation allows you to: * **Separate concerns**: Each subgraph owns a specific domain * **Scale independently**: Subgraphs can be deployed and scaled separately * **Compose seamlessly**: The gateway stitches subgraphs into one unified API * **Extend types**: Subgraphs can add fields to types defined elsewhere ## Architecture Overview ```mermaid theme={null} graph TD Gateway[GraphQL Gateway
Apollo Router] Gateway --> Assets[su-assets
Asset Profiles] Gateway --> Auth[su-auth
Authentication] Gateway --> CAM[su-cam-assets
Connected Assets] Gateway --> Issues[su-issues
Issue Tracking] Gateway --> LDAR[su-methane-ldar-backend
LDAR Operations] Gateway --> Workflow[su-workflow
Workflows] Gateway --> Forms[su-forms
XForms] Gateway --> Maps[su-maps
Geospatial] Gateway --> More[... 7 more subgraphs] style Gateway fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff style Assets fill:#7B68EE,stroke:#5A4CB8,color:#fff style Auth fill:#7B68EE,stroke:#5A4CB8,color:#fff style CAM fill:#7B68EE,stroke:#5A4CB8,color:#fff style Issues fill:#7B68EE,stroke:#5A4CB8,color:#fff style LDAR fill:#7B68EE,stroke:#5A4CB8,color:#fff style Workflow fill:#7B68EE,stroke:#5A4CB8,color:#fff style Forms fill:#7B68EE,stroke:#5A4CB8,color:#fff style Maps fill:#7B68EE,stroke:#5A4CB8,color:#fff style More fill:#9B9B9B,stroke:#6B6B6B,color:#fff ``` When you query the gateway: 1. Gateway receives your GraphQL query 2. Creates a query plan across relevant subgraphs 3. Executes queries against subgraphs (in parallel where possible) 4. Stitches results together 5. Returns unified response ## Key Federation Concepts ### Entities Entities are types that can be referenced and extended across subgraphs. They're marked with the `@key` directive. ```graphql theme={null} type Asset @key(fields: "profile id") { profile: ID! id: ID! displayName: String! } ``` The `@key` directive specifies the fields needed to uniquely identify an instance of this type. ### Type Extensions Subgraphs can extend types defined in other subgraphs using `@extends`: ```graphql theme={null} type Asset @key(fields: "profile id") @extends { profile: ID! @external id: ID! @external issueSubject: IssueSubject! # Added by su-issues subgraph } ``` This allows the `su-issues` subgraph to add the `issueSubject` field to the `Asset` type originally defined in `su-assets`. ### Entity Resolution When a subgraph needs to resolve an entity, it provides a reference resolver: ```javascript theme={null} // In su-issues subgraph { Asset: { __resolveReference(reference) { // reference = { profile: "wells", id: "well-123" } // Return asset-specific issue information return { profile: reference.profile, id: reference.id, issueSubject: getIssueSubjectForAsset(reference) } } } } ``` ## SensorUp Federation Structure ### Entity Ownership | Entity | Owner | Extended By | | - | - | - | | `Asset` | su-assets | su-issues, su-eventhub | | `User` | su-user | su-auth | | `Site` | su-sites | su-methane-ldar-backend | | `Issue` | su-issues | (none) | | `EmissionObservation` | su-methane-ldar-backend | (none) | ### Shared Types Some types are marked `@shareable`, meaning multiple subgraphs can define them: ```graphql theme={null} type PageInfo @shareable { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } ``` Common shareable types: * `PageInfo` - Pagination metadata * `GeoJSON*` types - Geospatial types * Scalar types - `DateTime`, `JSONObject` ## Cross-Subgraph Queries Federation enables queries that span multiple subgraphs seamlessly. ### Example: Asset with Issue Information ```graphql theme={null} query GetAssetWithIssues($profile: ID!, $assetId: ID!) { assetProfiles { # su-assets subgraph byId(profile: $profile) { assetById(id: $assetId) { id displayName # su-assets properties # su-assets issueSubject { # su-issues extends Asset type reference issues { # su-issues id title status } } } } } } ``` The gateway: 1. Queries `su-assets` for asset data 2. Takes the asset reference 3. Queries `su-issues` for issue information 4. Merges the results ### Example: User with Authentication ```graphql theme={null} query GetUserDetails($userId: ID!) { user(id: $userId) { # su-user subgraph id name # su-user email # su-user devices { # su-auth extends User deviceKey # su-auth name # su-auth lastSignedInAt # su-auth } } } ``` ## Federation Directives ### @key Marks a type as an entity with a unique key: ```graphql theme={null} type Asset @key(fields: "profile id") { profile: ID! id: ID! # ... } ``` Multiple keys are supported: ```graphql theme={null} type Asset @key(fields: "profile id") @key(fields: "catalogId dataset assetId") { # ... } ``` ### @extends Indicates a type is being extended from another subgraph: ```graphql theme={null} type Asset @key(fields: "profile id") @extends { profile: ID! @external id: ID! @external newField: String! } ``` ### @external Marks fields that are defined in another subgraph: ```graphql theme={null} type Asset @key(fields: "profile id") @extends { profile: ID! @external id: ID! @external computedField: String! @requires(fields: "profile id") } ``` ### @requires Specifies fields needed from the base type to resolve a field: ```graphql theme={null} type Asset @key(fields: "profile id") @extends { profile: ID! @external displayName: String! @external enrichedName: String! @requires(fields: "displayName") } ``` ### @provides Optimizes queries by providing fields from related entities: ```graphql theme={null} type AssetProfile @key(fields: "profile") { upSpecification: UpSpecification @provides(fields: "catalogId dataset") } ``` ### @shareable Allows multiple subgraphs to define the same type/field: ```graphql theme={null} type PageInfo @shareable { hasNextPage: Boolean! hasPreviousPage: Boolean! } ``` ## Query Planning The gateway creates an optimized query plan for each request. ### Simple Query ```graphql theme={null} query { session { username authenticated } } ``` Query plan: ``` QueryPlan { Fetch(service: "su-auth") { { session { username authenticated } } } } ``` ### Cross-Subgraph Query ```graphql theme={null} query { assetProfiles { byId(profile: "wells") { assets(first: 10) { edges { node { id displayName # su-assets issueSubject { # su-issues issues { id title } } } } } } } } ``` Query plan: ``` QueryPlan { Sequence { Fetch(service: "su-assets") { { assetProfiles { byId(profile: "wells") { assets(first: 10) { edges { node { __typename profile id displayName } } } } }} }, Flatten(path: "assetProfiles.byId.assets.edges.@.node") { Fetch(service: "su-issues") { { ... on Asset { __typename profile id issueSubject { issues { id title } } }} } } } } ``` ## Performance Considerations ### Parallel Execution Federation executes independent fetches in parallel: ```graphql theme={null} query { session { # su-auth - fetched in parallel username } assetProfiles { # su-assets - fetched in parallel all(first: 10) { edges { node { title } } } } } ``` ### N+1 Problem Be aware of the N+1 problem with entity references: ```graphql theme={null} query { issues { all(first: 100) { edges { node { id subject { assetReference { asset { # Potentially 100 lookups to su-assets! displayName } } } } } } } } ``` **Solution**: Federation batches entity resolutions using DataLoader-like mechanisms. ## Debugging Federation ### Query Plan Visualization Use Apollo Studio to visualize query plans and identify performance bottlenecks. ### Subgraph Errors When a subgraph fails, the error includes the service name: ```json theme={null} { "errors": [ { "message": "Failed to fetch from subgraph 'su-assets'", "extensions": { "serviceName": "su-assets", "code": "SUBREQUEST_HTTP_ERROR" } } ] } ``` ### Trace Subgraph Calls Monitor subgraph execution times: ```json theme={null} { "extensions": { "ftv1": "base64-encoded-trace-data" } } ``` ## Best Practices 1. **Design entity keys carefully**: Choose stable, immutable fields for `@key` 2. **Minimize entity hops**: Deeply nested cross-subgraph queries can be slow 3. **Use @provides sparingly**: Only when it significantly reduces fetches 4. **Batch related queries**: Combine multiple operations in one request 5. **Monitor query plans**: Use Apollo Studio to identify inefficient plans 6. **Handle partial failures**: Subgraph failures may return partial data 7. **Version subgraph changes**: Coordinate breaking changes across subgraphs 8. **Test entity resolution**: Ensure reference resolvers handle all key combinations ## Differences from Schema Stitching | Feature | Federation | Schema Stitching | | - | - | - | | Type ownership | Clear owner per type | Ambiguous | | Type extension | Native support | Manual | | Query planning | Automatic | Manual | | Performance | Optimized | Variable | | DX | Better | Complex | ## Resources * **[Apollo Federation Documentation](https://www.apollographql.com/docs/federation/)** * **[Subgraph Reference](./subgraphs/assets)** - SensorUp subgraph schemas * **[Performance Guide](./performance)** - Optimization strategies ## Studio Access For detailed query planning and performance monitoring, access Apollo Studio: [https://studio.apollographql.com/graph/su-graphql-t912yf/](https://studio.apollographql.com/graph/su-graphql-t912yf/) (Contact your SensorUp account team for access) # Connected Asset Management Guide Source: https://docs.sensorup.com/api/graphql/guides/cam-assets Working with asset types, properties, and asset hierarchy in the SensorUp Connected Asset Management (CAM) system. # Connected Asset Management Guide The Connected Asset Management (CAM) API provides comprehensive asset management capabilities for connected operations through the `su-cam-assets` subgraph. CAM handles asset types, asset properties, asset hierarchy, and geospatial operations. ## Overview CAM enables you to: * Define and manage **asset types** with custom property schemas * Create and organize **assets** with hierarchical relationships * Query assets by type, location, and properties * Perform batch operations for large-scale asset management * Track asset states and status changes * Manage geospatial data and relationships ## Core Concepts ### Asset Types Asset types define the schema and structure for assets. Each asset type specifies: * **Properties**: Custom attributes and their data types * **Hierarchy**: Parent-child relationships between assets * **Extensions**: External data source integrations * **Status tracking**: Asset state management configuration ### Assets Assets are instances of asset types representing physical or logical entities in your connected operations: * **Sites**: Top-level geographic locations * **Equipment**: Major operational assets * **Components**: Sub-components within equipment * **Wells**: Oil and gas well assets * **Pipelines**: Pipeline infrastructure * **Unattributed**: Assets not yet assigned to a specific type ### Asset Hierarchy Assets can be organized in parent-child relationships, enabling: * Multi-level organizational structures * Inherited properties and configurations * Hierarchical queries and filtering * Geographic nesting (e.g., equipment within sites) ## Querying Assets ### Get All Asset Types ```graphql theme={null} query GetAssetTypes { assetTypes { all(first: 20) { edges { node { assetTypeId name description properties { id name dataType required } } } pageInfo { hasNextPage endCursor } } } } ``` ### Get Specific Asset Type ```graphql theme={null} query GetAssetType($assetTypeId: ID!) { assetTypes { byId(assetTypeId: $assetTypeId) { assetTypeId name description properties { id name dataType required defaultValue } extensions { id name connectionDetails { ... on AssetTypeExtensionConnectionSimple { idProperty idColumn stateProperty } } } } } } ``` **Variables:** ```json theme={null} { "assetTypeId": "site" } ``` ### Query Assets by Type ```graphql theme={null} query GetAssetsByType($assetTypeId: ID!) { camAssets(assetTypeId: $assetTypeId) { all(first: 20) { edges { node { id name description assetTypeId active geometry { type coordinates } properties parent { id name } children { id name assetTypeId } } } pageInfo { hasNextPage endCursor } } } } ``` **Variables:** ```json theme={null} { "assetTypeId": "equipment" } ``` ### Query Asset by ID ```graphql theme={null} query GetAsset($id: ID!) { camAssets { byId(id: $id) { id name description assetTypeId active geometry { type coordinates } properties parent { id name assetTypeId } status { statusId label setAt setBy } } } } ``` **Variables:** ```json theme={null} { "id": "site-001" } ``` ### Filter and Search Assets ```graphql theme={null} query SearchAssets($assetTypeId: ID!, $searchText: String!) { camAssets(assetTypeId: $assetTypeId) { all( first: 20 fullTextSearch: { text: $searchText } filter: { active: true } ) { edges { node { id name description assetTypeId } } totalCount } } } ``` **Variables:** ```json theme={null} { "assetTypeId": "site", "searchText": "compressor" } ``` ## Creating and Updating Assets ### Create an Asset ```graphql theme={null} mutation CreateAsset($input: CreateAssetInput!) { createAsset(input: $input) { asset { id name assetTypeId properties } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "assetId": "site-abc", "name": "Compressor Station ABC", "description": "Primary compression facility", "assetTypeId": "site", "active": true, "group": "your-tenant-id", "geometry": { "type": "Point", "coordinates": [-114.0719, 51.0447] }, "propertyValues": [ { "propertyId": "operator", "value": "ACME Energy" }, { "propertyId": "capacity", "value": "5000" } ] } } ``` ### Update Asset Properties ```graphql theme={null} mutation UpdateAssetProperty($input: UpdateAssetPropertyInput!) { updateAssetProperty(input: $input) { asset { id properties } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "assetId": "site-abc", "group": "your-tenant-id", "propertyValues": [ { "propertyId": "capacity", "value": "6000" } ] } } ``` ### Update Asset Geometry ```graphql theme={null} mutation UpdateAssetGeometry($input: UpdateAssetGeometryInput!) { updateAssetGeometry(input: $input) { asset { id geometry { type coordinates } } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "assetId": "site-abc", "group": "your-tenant-id", "geometry": { "type": "Polygon", "coordinates": [[ [-114.073, 51.045], [-114.071, 51.045], [-114.071, 51.044], [-114.073, 51.044], [-114.073, 51.045] ]] } } } ``` ### Create Asset Status Record ```graphql theme={null} mutation CreateAssetStatus($input: CreateAssetStatusInput!) { createAssetStatus(input: $input) { assetStatus { assetId statusId label setAt setBy } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "assetId": "equipment-001", "group": "your-tenant-id", "statusId": "operational", "label": "Fully Operational", "notes": "Post-maintenance verification complete" } } ``` ## Batch Operations For large-scale asset creation or updates, CAM provides batch upsert capabilities. ### Generate Batch Upload URL ```graphql theme={null} query GenerateUploadUrl($input: GenerateBatchUpsertUploadUrlInput!) { generateBatchUpsertUploadUrl(input: $input) { uploadUrl batchUpsertReference expiresAt } } ``` **Variables:** ```json theme={null} { "input": { "assetTypeId": "equipment", "fileFormat": "CSV", "fileName": "equipment_batch_update.csv", "fileSizeBytes": 2048000, "group": "your-tenant-id", "expirationMinutes": 60 } } ``` ### Upload File and Trigger Batch Upsert ```javascript theme={null} // 1. Get the upload URL const { data } = await client.query({ query: GENERATE_UPLOAD_URL, variables: { input: uploadParams } }) // 2. Upload file to S3 await fetch(data.generateBatchUpsertUploadUrl.uploadUrl, { method: 'PUT', headers: { 'Content-Type': 'text/csv' }, body: csvFileContent }) // 3. Trigger batch processing await client.mutate({ mutation: gql` mutation BatchUpsert($ref: String!) { manageCamAssets(dryRun: false) { batchUpsert(batchUpsertReference: $ref) { success processedCount errors { row message } } } } `, variables: { ref: data.generateBatchUpsertUploadUrl.batchUpsertReference } }) ``` ## Asset Hierarchy Operations ### Query Asset Hierarchy ```graphql theme={null} query GetAssetHierarchy($rootId: ID!) { camAssets { byId(id: $rootId) { id name assetTypeId children { id name assetTypeId children { id name assetTypeId } } } } } ``` ### Create Child Asset ```graphql theme={null} mutation CreateChildAsset($input: CreateAssetInput!) { createAsset(input: $input) { asset { id name parent { id name } } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "assetId": "compressor-001", "name": "Compressor Unit 1", "assetTypeId": "equipment", "active": true, "group": "your-tenant-id", "parent": { "assetId": "site-abc", "assetTypeId": "site" }, "geometry": { "type": "Point", "coordinates": [-114.0720, 51.0448] } } } ``` ## Geospatial Queries CAM supports full GeoJSON geometry types for asset locations: ### Query Assets by Bounding Box ```graphql theme={null} query GetAssetsInBounds( $assetTypeId: ID! $minLon: Float! $minLat: Float! $maxLon: Float! $maxLat: Float! ) { camAssets(assetTypeId: $assetTypeId) { all( first: 100 filter: { geometry: { bbox: [$minLon, $minLat, $maxLon, $maxLat] } } ) { edges { node { id name geometry { type coordinates bbox } } } } } } ``` ### Supported Geometry Types CAM supports all GeoJSON geometry types: * **Point**: Single location `[-114.0719, 51.0447]` * **LineString**: Linear features (pipelines, roads) * **Polygon**: Areas and boundaries * **MultiPoint**, **MultiLineString**, **MultiPolygon**: Collections * **GeometryCollection**: Mixed geometry types ## Asset References Query lightweight asset references for dropdowns and lookups: ```graphql theme={null} query GetAssetReferences { camAssetReferences { all(first: 100) { edges { node { id name assetTypeId } } } } } ``` ## CAM Engine and Datasets Query available datasets and engine configuration: ```graphql theme={null} query GetCamEngine { camEngine { datasets { id name assetTypeId sourceType } } } ``` ### Get Datasets for Tenant ```graphql theme={null} query GetCamDatasets($group: ID!) { camAssetsDatasets(group: $group) { dataset displayName assetTypeId } } ``` ## Asset Configuration Manage tenant-specific asset configurations: ```graphql theme={null} query GetAssetConfigs($group: ID!) { assetConfigs(group: $group) { all { id value } } } ``` ### Set Configuration ```graphql theme={null} mutation SetAssetConfig($group: ID!, $id: ID!, $value: JSONObject!) { setAssetConfig(group: $group, id: $id, value: $value) { config { id value } correlationId errors { message type } } } ``` ## Best Practices ### 1. Use Asset Type Filtering Always filter by `assetTypeId` when querying assets to improve performance: ```graphql theme={null} # Good - filtered by type camAssets(assetTypeId: "equipment") { all(first: 20) { ... } } # Less efficient - all asset types camAssets { all(first: 20) { ... } } ``` ### 2. Batch Operations for Scale For bulk operations (>100 assets), use batch upsert instead of individual mutations: ```graphql theme={null} # Good for >100 assets generateBatchUpsertUploadUrl → upload CSV → manageCamAssets.batchUpsert # Use individual mutations for <100 assets createAsset, updateAsset ``` ### 3. Request Only Needed Fields Minimize query size by selecting only required fields: ```graphql theme={null} # Good - specific fields camAssets { byId(id: "x") { id name } } # Avoid - requesting all properties camAssets { byId(id: "x") { id name properties ... } } ``` ### 4. Use Asset References for Lookups For dropdowns and selection lists, use `camAssetReferences` instead of full `camAssets`: ```graphql theme={null} # Good - lightweight references camAssetReferences { all { edges { node { id name } } } } # Avoid - full asset queries for simple lookups camAssets { all { edges { node { id name ... } } } } ``` ### 5. Leverage Asset Hierarchy Use parent-child relationships instead of flat structures: ```graphql theme={null} # Good - hierarchical query camAssets { byId(id: "site-001") { children { # Equipment at site children { # Components on equipment id name } } } } ``` ## Error Handling CAM mutations return errors in the standard format: ```json theme={null} { "data": { "createAsset": { "asset": null, "correlationId": "abc-123", "errors": [ { "message": "Asset with ID 'site-abc' already exists", "type": "DUPLICATE_ID" } ] } } } ``` Common error types: * `DUPLICATE_ID`: Asset ID already exists * `INVALID_PARENT`: Parent asset not found or invalid type * `INVALID_PROPERTY`: Property validation failed * `INVALID_GEOMETRY`: GeoJSON geometry is malformed * `MISSING_REQUIRED`: Required field not provided ## Related Resources * **[Subgraph Reference](../subgraphs/cam-assets)** - Complete schema documentation * **[Common Patterns](../common-patterns)** - Pagination and filtering * **[Field Service Guide](./field-service)** - Mobile workflows using assets * **[Core Platform Guide](./core-platform)** - Maps and geospatial services # Core Platform Guide Source: https://docs.sensorup.com/api/graphql/guides/core-platform Working with platform services including authentication, user management, geospatial operations, data catalogs, and event streaming. # Core Platform Guide The Core Platform API provides foundational services that underpin all SensorUp operations. It includes authentication (`su-auth`), user management (`su-user`), core infrastructure (`su-backend`), geospatial services (`su-maps`), data catalogs (`su-catalog`), and event streaming (`su-eventhub`). ## Overview The Core Platform enables: * **Authentication**: Session management, API keys, and federated sign-in * **User Management**: User profiles, permissions, and device tracking * **Geospatial Services**: Maps, location queries, and spatial operations * **Data Catalogs**: Schema registry and metadata management * **Event Streaming**: Real-time event subscriptions and notifications * **Core Infrastructure**: Configuration, health checks, and system operations ## Authentication (su-auth) For comprehensive authentication documentation, see the **[Authentication Guide](../authentication)**. ### Quick Reference **Session-based Authentication:** ```graphql theme={null} mutation SignIn($input: AuthSignInInput!) { signIn(input: $input) { session { username authenticated expiresAt expiresAtHard userGroup } correlationId errors { message type } } } ``` **Check Current Session:** ```graphql theme={null} query { session { username authenticated expiresAt userGroup lastAuthenticatedAt } } ``` **API Key Creation:** ```graphql theme={null} mutation CreateAPIKey($input: AuthCreateAPIKeyInput!) { createAPIKey(input: $input) { apiKey { apiKeyId apiKeySessionId expiresAt } correlationId errors { message type } } } ``` ### Session Lifetimes | Client Type | Hard Expiry | Soft Expiry (Idle) | | - | - | - | | Explorer (Web) | 30 days | 7 days | | SensorHub Android | 365 days | 60 days | | SensorHub iOS | 365 days | 60 days | | API Key | 365 days | 60 days | ### Authentication Methods * **Cookie**: `sensorup_sessionid` (auto-set in browser) * **Header**: `x-sensorup-sessionid` (for API clients and M2M) ```bash theme={null} curl -X POST https://customer-demo.sensorup.com/api/graphql \ -H "Content-Type: application/json" \ -H "x-sensorup-sessionid: YOUR_SESSION_ID" \ -d '{"query":"{ session { username } }"}' ``` ## User Management (su-user) ### Query User Profile ```graphql theme={null} query GetUser($userId: ID!) { user(id: $userId) { userId username email firstName lastName phoneNumber preferredLanguage timezone groups permissions { resource actions } devices { deviceKey name remembered lastSignedInAt lastIpAddress } } } ``` ### Update User Profile ```graphql theme={null} mutation UpdateUser($input: UpdateUserInput!) { updateUser(input: $input) { user { userId firstName lastName email phoneNumber } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "userId": "user-123", "firstName": "John", "lastName": "Smith", "phoneNumber": "+1-555-0100", "timezone": "America/Edmonton" } } ``` ### Query User Permissions ```graphql theme={null} query GetUserPermissions($userId: ID!) { user(id: $userId) { userId username groups permissions { resource actions scope } roles { roleId roleName permissions { resource actions } } } } ``` ### List Users in Group ```graphql theme={null} query GetGroupUsers($group: ID!) { users(group: $group) { all(first: 100) { edges { node { userId username email firstName lastName active } } pageInfo { hasNextPage endCursor } } } } ``` ### Device Management ```graphql theme={null} query GetUserDevices($userId: ID!) { user(id: $userId) { devices { deviceKey name remembered createdAt lastSignedInAt lastIpAddress userAgent } } } ``` **Forget Device:** ```graphql theme={null} mutation ForgetDevice($input: AuthForgetSpecificDevicesInput!) { forgetDevices(input: $input) { session { username } correlationId errors { message type } } } ``` ## Geospatial Services (su-maps) ### Query Map Configuration ```graphql theme={null} query GetMapConfig { maps { config { defaultCenter { lat lon } defaultZoom baseLayers { id name type url attribution } overlayLayers { id name type url } } } } ``` ### Get Map Tiles ```graphql theme={null} query GetMapTiles($bounds: BoundsInput!, $zoom: Int!) { maps { tiles(bounds: $bounds, zoom: $zoom) { tileUrl bounds { north south east west } zoom } } } ``` **Variables:** ```json theme={null} { "bounds": { "north": 51.1, "south": 51.0, "east": -114.0, "west": -114.1 }, "zoom": 12 } ``` ### Geocoding ```graphql theme={null} query Geocode($address: String!) { maps { geocode(address: $address) { results { formattedAddress geometry { location { lat lon } bounds { north south east west } } placeId types } } } } ``` **Variables:** ```json theme={null} { "address": "Calgary, Alberta, Canada" } ``` ### Reverse Geocoding ```graphql theme={null} query ReverseGeocode($lat: Float!, $lon: Float!) { maps { reverseGeocode(lat: $lat, lon: $lon) { results { formattedAddress addressComponents { longName shortName types } placeId } } } } ``` **Variables:** ```json theme={null} { "lat": 51.0447, "lon": -114.0719 } ``` ### Spatial Queries ```graphql theme={null} query FindNearbyAssets($location: LocationInput!, $radiusKm: Float!) { maps { findNearby(location: $location, radius: $radiusKm) { results { id type distance geometry { type coordinates } properties } } } } ``` **Variables:** ```json theme={null} { "location": { "lat": 51.0447, "lon": -114.0719 }, "radiusKm": 10.0 } ``` ### GeoJSON Support The platform supports full GeoJSON geometry types: ```graphql theme={null} type GeoJSONGeometry { type: GeoJSONType! # Point, LineString, Polygon, etc. coordinates: GeoJSONCoordinates bbox: [Float] } enum GeoJSONType { Point MultiPoint LineString MultiLineString Polygon MultiPolygon GeometryCollection Feature FeatureCollection } ``` **Example Point:** ```json theme={null} { "type": "Point", "coordinates": [-114.0719, 51.0447] } ``` **Example Polygon:** ```json theme={null} { "type": "Polygon", "coordinates": [[ [-114.073, 51.045], [-114.071, 51.045], [-114.071, 51.044], [-114.073, 51.044], [-114.073, 51.045] ]] } ``` ## Data Catalogs (su-catalog) ### Query Catalog Entries ```graphql theme={null} query GetCatalogEntries { catalog { entries(first: 100) { edges { node { id name description schema dataType category tags createdAt updatedAt } } pageInfo { hasNextPage endCursor } } } } ``` ### Get Specific Catalog Entry ```graphql theme={null} query GetCatalogEntry($id: ID!) { catalog { entry(id: $id) { id name description schema dataType category tags metadata validationRules { rule message } } } } ``` ### Create Catalog Entry ```graphql theme={null} mutation CreateCatalogEntry($input: CreateCatalogEntryInput!) { createCatalogEntry(input: $input) { catalogEntry { id name schema } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "id": "pressure-reading", "name": "Pressure Reading", "description": "Equipment pressure sensor reading", "dataType": "numeric", "schema": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": ["psi", "kPa", "bar"] }, "timestamp": { "type": "string", "format": "date-time" } }, "required": ["value", "unit", "timestamp"] }, "category": "sensor-data", "tags": ["pressure", "sensor", "telemetry"] } } ``` ### Query by Category ```graphql theme={null} query GetCatalogByCategory($category: String!) { catalog { byCategory(category: $category) { id name description dataType } } } ``` **Variables:** ```json theme={null} { "category": "sensor-data" } ``` ## Event Streaming (su-eventhub) ### Subscribe to Events ```graphql theme={null} subscription OnEvents($filter: EventFilter) { events(filter: $filter) { eventId eventType source timestamp data correlationId } } ``` **Variables (Filter by Event Type):** ```json theme={null} { "filter": { "eventTypes": ["ASSET_CREATED", "ASSET_UPDATED", "ISSUE_CREATED"] } } ``` ### Publish Event ```graphql theme={null} mutation PublishEvent($input: PublishEventInput!) { publishEvent(input: $input) { event { eventId eventType timestamp } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "eventType": "CUSTOM_EVENT", "source": "integration-service", "data": { "action": "data_sync_completed", "recordsProcessed": 1500, "duration": 45.2 } } } ``` ### Query Event History ```graphql theme={null} query GetEventHistory($filter: EventFilter!, $first: Int!) { eventHub { history(filter: $filter, first: $first) { edges { node { eventId eventType source timestamp data } } pageInfo { hasNextPage endCursor } } } } ``` **Variables:** ```json theme={null} { "filter": { "eventTypes": ["ASSET_CREATED"], "from": "2025-11-01T00:00:00Z", "to": "2025-11-05T23:59:59Z" }, "first": 100 } ``` ### Event Types Common system event types: | Event Type | Description | | - | - | | `ASSET_CREATED` | New asset created | | `ASSET_UPDATED` | Asset modified | | `ASSET_DELETED` | Asset removed | | `ISSUE_CREATED` | New issue opened | | `ISSUE_UPDATED` | Issue modified | | `ISSUE_CLOSED` | Issue resolved and closed | | `DETECTION_CREATED` | New detection recorded | | `FORM_SUBMITTED` | XForm response submitted | | `USER_SIGNED_IN` | User authentication | | `API_KEY_CREATED` | New API key generated | ## Core Infrastructure (su-backend) ### System Configuration ```graphql theme={null} query GetConfig { config { environment version features { name enabled configuration } auth { loginEnabled ssoEnabled ssoUrl mfaRequired } integrations { name type endpoint active } } } ``` ### Health Check ```graphql theme={null} query HealthCheck { health { status version timestamp services { name status latency lastCheck } } } ``` ### Feature Flags ```graphql theme={null} query GetFeatureFlags { features { all { featureId name enabled rolloutPercentage conditions { type value } } } } ``` **Check Specific Feature:** ```graphql theme={null} query IsFeatureEnabled($featureId: ID!, $context: FeatureContext) { features { isEnabled(featureId: $featureId, context: $context) } } ``` ### System Metrics ```graphql theme={null} query GetSystemMetrics { metrics { apiCalls { total byEndpoint { endpoint count avgLatency } } errors { total byType { type count } } performance { avgResponseTime p95ResponseTime p99ResponseTime } } } ``` ## Common Patterns ### Authentication Flow ```javascript theme={null} // 1. Sign in const { data } = await client.mutate({ mutation: SIGN_IN, variables: { input: { loginUsername: 'user@example.com', password: 'password', clientApplicationType: 'EXPLORER' } } }) // 2. Store session ID const sessionId = data.signIn.session.sessionId // 3. Use in subsequent requests const result = await fetch('https://customer-demo.sensorup.com/api/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-sensorup-sessionid': sessionId }, body: JSON.stringify({ query: '{ session { username } }' }) }) ``` ### Geospatial Queries ```javascript theme={null} // Find assets near a location async function findAssetsNearLocation(lat, lon, radiusKm) { const { data } = await client.query({ query: FIND_NEARBY, variables: { location: { lat, lon }, radiusKm } }) return data.maps.findNearby.results } // Geocode an address async function getCoordinates(address) { const { data } = await client.query({ query: GEOCODE, variables: { address } }) return data.maps.geocode.results[0].geometry.location } ``` ### Event Streaming ```javascript theme={null} // Subscribe to real-time events const subscription = client.subscribe({ query: ON_EVENTS, variables: { filter: { eventTypes: ['ASSET_CREATED', 'ISSUE_CREATED'] } } }).subscribe({ next: ({ data }) => { console.log('New event:', data.events) handleEvent(data.events) }, error: (error) => console.error('Subscription error:', error) }) // Cleanup subscription.unsubscribe() ``` ### Catalog-Driven Forms ```javascript theme={null} // Use catalog to validate form data async function validateFormData(dataType, data) { // Get schema from catalog const { data: catalogData } = await client.query({ query: GET_CATALOG_ENTRY, variables: { id: dataType } }) const schema = catalogData.catalog.entry.schema // Validate against schema const valid = validateAgainstJsonSchema(data, schema) return valid } ``` ## Best Practices ### 1. Session Management Monitor session expiration and refresh proactively: ```javascript theme={null} // Check session expiration const { data } = await client.query({ query: GET_SESSION }) const expiresAt = new Date(data.session.expiresAt) const now = new Date() // Refresh if expiring soon (within 1 hour) if (expiresAt - now < 3600000) { await refreshSession() } ``` ### 2. Geospatial Performance Use appropriate zoom levels and bounds for map tiles: ```graphql theme={null} # Good - reasonable bounds maps { tiles(bounds: { ... }, zoom: 12) } # Avoid - excessive detail over large area maps { tiles(bounds: { ... }, zoom: 18) } ``` ### 3. Event Filtering Subscribe only to needed event types: ```graphql theme={null} # Good - filtered subscription subscription { events(filter: { eventTypes: ["ASSET_CREATED"] }) } # Avoid - unfiltered (high volume) subscription { events } ``` ### 4. Catalog Validation Leverage catalog schemas for data validation: ```graphql theme={null} # 1. Get schema from catalog catalog { entry(id: "sensor-reading") { schema } } # 2. Validate data client-side before submission # 3. Submit validated data ``` ### 5. Permission Checks Always verify user permissions before restricted operations: ```graphql theme={null} query CheckPermission($userId: ID!, $resource: String!, $action: String!) { user(id: $userId) { permissions { resource actions } } } ``` ## Error Handling Platform mutations return consistent error formats: ```json theme={null} { "data": { "updateUser": { "user": null, "correlationId": "abc-123", "errors": [ { "message": "Invalid email address format", "type": "VALIDATION_ERROR" } ] } } } ``` Common error types: * `AUTHENTICATION_FAILED`: Invalid credentials * `AUTHORIZATION_FAILED`: Insufficient permissions * `VALIDATION_ERROR`: Input validation failed * `NOT_FOUND`: Resource does not exist * `DUPLICATE`: Resource already exists * `RATE_LIMIT_EXCEEDED`: Too many requests ## Related Resources * **[Authentication Guide](../authentication)** - Comprehensive auth documentation * **[Auth Subgraph Reference](../subgraphs/auth)** - Complete auth schema * **[User Subgraph Reference](../subgraphs/user)** - User management schema * **[Maps Subgraph Reference](../subgraphs/maps)** - Geospatial schema * **[Catalog Subgraph Reference](../subgraphs/catalog)** - Catalog schema * **[EventHub Subgraph Reference](../subgraphs/eventhub)** - Event streaming schema * **[Backend Subgraph Reference](../subgraphs/backend)** - Core infrastructure schema * **[Common Patterns](../common-patterns)** - Pagination, filtering, and error handling # Emissions & LDAR API Guide Source: https://docs.sensorup.com/api/graphql/guides/emissions Learn how to work with emission observations, LDAR workflows, reconciliation, and detection ingestion. # Emissions & LDAR API Guide The Emissions API provides comprehensive Leak Detection and Repair (LDAR) capabilities through three specialized subgraphs: `su-methane-ldar-backend`, `su-methane-reconcile-backend`, and `su-detections-ingress`. ## Overview The Emissions API enables you to: * Track and manage emission observations (detections) * Coordinate LDAR inspection workflows * Reconcile emissions for compliance reporting * Ingest detection data from various sources ### Key Concepts * **Emission Observation**: A detected emission event requiring investigation * **Detection**: Raw detection data from sensors, flyovers, satellites, etc. * **Inspection Request**: Request for follow-up inspection (OGI, drone, visual) * **Reconciliation**: Process of matching emissions to compliance requirements * **Clue**: Additional context about a detection (equipment, location, etc.) ## Emission Observations ### Query Emission Observations ```graphql theme={null} query GetEmissionObservations($first: Int!, $after: String) { emissionObservations { all(first: $first, after: $after) { edges { node { id displayName priority status detectionType phenomenonTime receivedAt geometry { type coordinates } audit { createdTime acknowledgedTime acknowledgedBy { userId } } } } pageInfo { hasNextPage endCursor } } } } ``` ### Get Specific Emission Observation ```graphql theme={null} query GetEmissionObservation($id: ID!) { emissionObservations { byId(id: $id) { id displayName priority status detectionType phenomenonTime geometry { type coordinates } clues { clueId clue { displayName equipment { id name } } } inspectionRequests { inspectionRequestId inspectionRequest { id inspectionType status additionalComment } } } } } ``` ## Detection Types | Type | Description | Common Source | | - | - | - | | `DETECTION_TYPE_SATELLITE` | Satellite-based detection | Remote sensing | | `DETECTION_TYPE_FLYOVER` | Aircraft-based detection | Aerial surveys | | `DETECTION_TYPE_DRONE` | Drone-based detection | UAV inspection | | `DETECTION_TYPE_OGI` | Optical Gas Imaging | Ground inspection | | `DETECTION_TYPE_CMS` | Continuous Monitoring System | Fixed sensors | | `DETECTION_TYPE_OWD` | On-site Walk Down | Manual inspection | | `DETECTION_TYPE_VENTING_FLARING_BLOWDOWN` | Planned releases | Operations | ## Detection Status Workflow ```mermaid theme={null} stateDiagram-v2 [*] --> NEW NEW --> VISUAL_INSPECTION_SCHEDULED VISUAL_INSPECTION_SCHEDULED --> VISUAL_INSPECTION_COMPLETED VISUAL_INSPECTION_COMPLETED --> OGI_REQUESTED OGI_REQUESTED --> OGI_SCHEDULED OGI_SCHEDULED --> OGI_COMPLETED OGI_COMPLETED --> LEAK_REPAIR_SCHEDULED LEAK_REPAIR_SCHEDULED --> LEAK_REPAIRED LEAK_REPAIRED --> VERIFICATION_SCHEDULED VERIFICATION_SCHEDULED --> RESOLVED RESOLVED --> [*] NEW: New Detection VISUAL_INSPECTION_SCHEDULED: Visual Inspection Scheduled VISUAL_INSPECTION_COMPLETED: Visual Inspection Completed OGI_REQUESTED: OGI Requested OGI_SCHEDULED: OGI Scheduled OGI_COMPLETED: OGI Completed LEAK_REPAIR_SCHEDULED: Leak Repair Scheduled LEAK_REPAIRED: Leak Repaired VERIFICATION_SCHEDULED: Verification Scheduled RESOLVED: Resolved ``` ## Priority Levels | Priority | Integer Value | Description | | - | - | - | | `DETECTION_PRIORITY_HIGH` | 100 | Requires immediate attention | | `DETECTION_PRIORITY_MEDIUM` | 50 | Normal priority | | `DETECTION_PRIORITY_LOW` | 1 | Low priority or informational | ## Inspection Requests Inspection requests coordinate follow-up investigations of emission observations. ### Create Inspection Request ```graphql theme={null} mutation CreateInspectionRequest($input: CreateInspectionRequestInput!) { createInspectionRequest(input: $input) { inspectionRequest { id detectionReference { detectionId } inspectionType status additionalComment audit { createdTime createdBy { userId } } } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "detectionReference": { "detectionId": "detection-123" }, "inspectionType": "INSPECTION_OGI", "additionalComment": "High priority - investigate equipment leak", "clues": [ { "clueId": "clue-456" } ], "requestedBy": { "givenName": "John", "familyName": "Doe", "email": "john.doe@example.com" } } } ``` ### Update Inspection Request ```graphql theme={null} mutation UpdateInspectionRequest($input: UpdateInspectionRequestInput!) { updateInspectionRequest(input: $input) { inspectionRequest { id status additionalComment } correlationId errors { message type } } } ``` ### Query Inspection Requests ```graphql theme={null} query GetInspectionRequests($detectionId: ID!) { emissionObservations { byId(id: $detectionId) { inspectionRequests { inspectionRequestId inspectionRequest { id inspectionType status additionalComment requestedBy { givenName familyName email } audit { createdTime updatedTime } } } } } } ``` ## Inspection Types | Type | Description | Typical Use | | - | - | - | | `INSPECTION_OGI` | Optical Gas Imaging | Confirm and locate leaks | | `INSPECTION_DRONE` | Drone inspection | Aerial investigation | ## Clues (Equipment Context) Clues provide context about where an emission was detected. ### Query Clues for Detection ```graphql theme={null} query GetDetectionClues($detectionId: ID!) { emissionObservations { byId(id: $detectionId) { clues { clueId clue { displayName equipment { id name description siteReference { siteId } components { name componentType } } } } } } } ``` ### Equipment Components ```graphql theme={null} query GetEquipmentComponents($equipmentId: ID!) { equipment { byId(id: $equipmentId) { id name components { name componentType description } } } } ``` ## Resolution Modes When resolving emission observations: | Mode | Description | | - | - | | `DETECTION_RESOLVED_CORRELATED` | Correlated with another detection | | `DETECTION_RESOLVED_FALSE_ALARM` | Determined to be false positive | | `DETECTION_RESOLVED_READY_TO_RECONCILE` | Ready for compliance reconciliation | ### Resolve Detection ```graphql theme={null} mutation ResolveDetection($input: ResolveDetectionInput!) { resolveDetection(input: $input) { emissionObservation { id status resolutionMode } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "detectionId": "detection-123", "resolutionMode": "DETECTION_RESOLVED_READY_TO_RECONCILE", "notes": "Verified and repaired, ready for compliance reporting" } } ``` ## Emission Observation Reports ### Query Reports by Site and Month ```graphql theme={null} query GetEmissionReports($siteId: ID!, $month: String!) { sites { byId(id: $siteId) { emissionObservationReports(month: $month) { edges { node { month totalDetections resolvedDetections pendingDetections highPriorityCount complianceStatus } } } } } } ``` **Variables:** ```json theme={null} { "siteId": "site-123", "month": "2025-11" } ``` ### Filter Reports ```graphql theme={null} query FilteredReports($filter: InboxDetectionFilter!) { emissionObservations { reports(filter: $filter) { edges { node { id displayName priority status } } } } } ``` ## Detection Ingress The `su-detections-ingress` subgraph handles incoming detection data. ### Query Available Datasets ```graphql theme={null} query GetDetectionDatasets($group: ID) { detectionsIngressDatasets(group: $group) { datasetId metadataJson } } ``` ### Reload Datasets ```graphql theme={null} mutation ReloadDatasets($group: ID) { reloadDetectionsIngressDatasets(group: $group) { datasetId metadataJson } } ``` ## Reconciliation Workflow The `su-methane-reconcile-backend` handles compliance reconciliation. ### Query Reconciliation Status ```graphql theme={null} query GetReconciliationStatus($siteId: ID!, $month: String!) { reconciliation { bySiteAndMonth(siteId: $siteId, month: $month) { status totalEmissions reconciledEmissions pendingEmissions complianceSeverity lastUpdated } } } ``` ### Submit for Reconciliation ```graphql theme={null} mutation SubmitForReconciliation($input: SubmitReconciliationInput!) { submitForReconciliation(input: $input) { reconciliation { id status submittedAt } correlationId errors { message type } } } ``` ## Compliance Severity | Severity | Description | | - | - | | `HIGH` | Critical compliance issue | | `MEDIUM` | Moderate compliance concern | | `LOW` | Minor compliance matter | ## Geospatial Queries ### Get Detections Near Location ```graphql theme={null} query GetNearbyDetections($center: GeoJSONGeometryInput!, $radius: Float!) { emissionObservations { near(center: $center, radius: $radius) { edges { node { id displayName geometry { type coordinates } distance } } } } } ``` **Variables:** ```json theme={null} { "center": { "type": "Point", "coordinates": [-114.0719, 51.0447] }, "radius": 1000 } ``` ## Audit & Acknowledgment ### Acknowledge Detection ```graphql theme={null} mutation AcknowledgeDetection($input: AcknowledgeDetectionInput!) { acknowledgeDetection(input: $input) { emissionObservation { id audit { acknowledgedTime acknowledgedBy { userId } } } correlationId errors { message type } } } ``` ### Query Acknowledgment History ```graphql theme={null} query GetAcknowledgmentHistory($detectionId: ID!) { emissionObservations { byId(id: $detectionId) { audit { createdTime createdBy { userId } updatedTime updatedBy { userId } acknowledgedTime acknowledgedBy { userId } } } } } ``` ## Common Patterns ### Processing New Detections ```javascript theme={null} // Query new detections const newDetections = await query(` query { emissionObservations { all(first: 100, filter: { status: DETECTION_STATUS_NEW }) { edges { node { id priority detectionType phenomenonTime } } } } } `) // Prioritize and create inspection requests for (const detection of newDetections.filter(d => d.priority === 'HIGH')) { await createInspectionRequest({ detectionId: detection.id, inspectionType: 'INSPECTION_OGI' }) } ``` ### Tracking Inspection Progress ```javascript theme={null} const inspectionStatuses = [ 'INSPECTION_STATUS_REQUESTED', 'INSPECTION_STATUS_SCHEDULED', 'INSPECTION_STATUS_COMPLETED' ] for (const status of inspectionStatuses) { const count = await countInspections({ status }) console.log(`${status}: ${count} inspections`) } ``` ## Best Practices 1. **Prioritize high-severity detections**: Focus on `DETECTION_PRIORITY_HIGH` first 2. **Track acknowledgment**: Always acknowledge when reviewing detections 3. **Use clues for context**: Clues help identify specific equipment and components 4. **Monitor status transitions**: Track detections through the complete workflow 5. **Coordinate inspections**: Link inspection requests to specific detections 6. **Reconcile regularly**: Don't let pending emissions accumulate 7. **Use geospatial queries**: Find nearby detections to optimize field work 8. **Archive resolved detections**: Keep historical data for compliance ## Related Resources * **[LDAR Backend Reference](../subgraphs/methane-ldar-backend)** - Complete schema * **[Reconcile Backend Reference](../subgraphs/methane-reconcile-backend)** - Reconciliation schema ## Schema Reference * [su-methane-ldar-backend SDL](../schemas/sdl/su-methane-ldar-backend.graphql) * [su-methane-reconcile-backend SDL](../schemas/sdl/su-methane-reconcile-backend.graphql) * [su-detections-ingress SDL](../schemas/sdl/su-detections-ingress.graphql) # Field Service Management Guide Source: https://docs.sensorup.com/api/graphql/guides/field-service Working with mobile workflows, issue tracking, task management, and data collection forms for field service operations. # Field Service Management Guide The Field Service Management (FSM) API enables mobile workflows through issue tracking, task management, and dynamic data collection forms. FSM integrates four subgraphs: `su-assets` (form subjects), `su-issues` (issue tracking), `su-workflow` (workflow orchestration), and `su-forms` (data collection). ## Overview FSM enables field teams to: * Track **issues** and work items requiring attention * Execute **workflows** with defined states and transitions * Complete **tasks** using dynamic XForms * Reference **asset profiles** as subjects for field work * Collect structured data through mobile applications * Manage multi-step inspection campaigns ## Core Concepts ### Asset Profiles (Form Subjects) Asset profiles (`su-assets`) define the subjects that field teams work on during mobile workflows. These are NOT the same as CAM assets: * **Asset Profile**: Schema definition for form subjects (e.g., "Well Inspection", "Equipment Survey") * **Asset**: Instance of a profile used as a form subject * **Properties**: Attributes collected about the subject * **Relationships**: Connections between assets and other entities Asset profiles serve as the foundation for tasks and forms in mobile applications. ### Issues Issues represent trackable work items requiring attention or resolution: * **Issue Types**: `ISSUE`, `TASK`, `MULTITASK`, `SUBTASK` * **Status**: `OPEN`, `IN_PROGRESS`, `RESOLVED`, `CLOSED`, `CANCELLED` * **Subject**: The entity the issue relates to (e.g., an asset profile instance) * **Trigger**: What caused the issue (e.g., a detection, event, or manual creation) ### Tasks Tasks are specific work to be performed by field personnel: * **Form-based Tasks**: Tasks with an associated XForm for data collection * **General Tasks**: Simple work items without form requirements * **Multi-tasks**: Parent tasks coordinating multiple subtasks * **Subtasks**: Individual tasks within a multi-task campaign ### XForms Dynamic data collection forms based on the ODK XForms standard: * **Controls**: Input fields (text, select, date, location, etc.) * **Groups**: Logical sections organizing related questions * **Repeats**: Repeating sections for multiple observations * **Constraints**: Validation rules and calculations * **Relevance**: Conditional display logic ### Workflows State machines defining the lifecycle of issues and tasks: * **States**: Valid statuses an issue can have * **Transitions**: Allowed movements between states * **Guards**: Conditions required for transitions * **Actions**: Side effects triggered during transitions ## Asset Profiles for Field Work ### Query Available Profiles ```graphql theme={null} query GetAssetProfiles { assetProfiles { all(first: 20) { edges { node { profile title displayNameProperty descriptionProperty properties { id name dataType required } relationships { relationship type profile referenceProperty } } } pageInfo { hasNextPage endCursor } } } } ``` ### Get Specific Profile ```graphql theme={null} query GetAssetProfile($profile: ID!) { assetProfiles { byId(profile: $profile) { profile title displayNameProperty views { view title fields } filters { filter displayName filterString } } } } ``` **Variables:** ```json theme={null} { "profile": "well-inspection" } ``` ### Query Assets (Form Subjects) ```graphql theme={null} query GetAssets($profile: ID!, $first: Int!) { assets(profile: $profile) { all(first: $first) { edges { node { id displayName properties geometry { type coordinates } relationships { ... on AssetRelationshipOne { asset { id displayName } } } } } pageInfo { hasNextPage endCursor } } } } ``` **Variables:** ```json theme={null} { "profile": "well-inspection", "first": 50 } ``` ### Create Asset (Form Subject) ```graphql theme={null} mutation CreateAsset($input: CreateAssetInput!) { createAsset(input: $input) { asset { id displayName properties } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "profile": "well-inspection", "id": "well-abc-123", "displayName": "Well ABC-123", "properties": { "operator": "ACME Energy", "wellType": "gas", "status": "active" }, "geometry": { "type": "Point", "coordinates": [-114.0719, 51.0447] } } } ``` ## Issue Tracking ### List All Issues ```graphql theme={null} query GetIssues($first: Int!, $filter: IssueFilter) { issues { all(first: $first, filter: $filter) { edges { node { id type title description status severity openedAt closedAt dueAt pastDue assignee { username } subject { type reference } trigger { type reference } } } pageInfo { hasNextPage endCursor } totalCount } } } ``` **Variables (Filter Open Issues):** ```json theme={null} { "first": 20, "filter": { "status": ["OPEN", "IN_PROGRESS"] } } ``` ### Get Specific Issue ```graphql theme={null} query GetIssue($id: ID!) { issues { byId(id: $id) { id type taskType title description status severity openedAt closedAt dueAt subject { type reference } assignee { userId username } annotations { id text createdAt createdBy { username } attachments { url filename contentType } } xform { formId responseId status } } } } ``` ### Create Issue ```graphql theme={null} mutation CreateIssue($input: CreateIssueInput!) { createIssue(input: $input) { issue { id title status type } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "title": "Quarterly Well Inspection - ABC-123", "description": "Routine quarterly inspection required", "type": "TASK", "severity": "MEDIUM", "dueAt": "2025-12-31T23:59:59Z", "subject": { "type": "ASSET", "reference": "well-abc-123" }, "assignee": { "userId": "user-123" } } } ``` ### Update Issue Status ```graphql theme={null} mutation UpdateIssue($input: UpdateIssueInput!) { updateIssue(input: $input) { issue { id status closedAt } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "id": "issue-123", "status": "RESOLVED" } } ``` ### Add Annotation to Issue ```graphql theme={null} mutation AddIssueAnnotation($input: AddIssueAnnotationInput!) { addIssueAnnotation(input: $input) { annotation { id text createdAt createdBy { username } } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "issueId": "issue-123", "text": "Inspection completed. No issues found. Equipment operating normally.", "attachments": [ { "url": "https://storage.example.com/photos/inspection-photo.jpg", "filename": "inspection-photo.jpg", "contentType": "image/jpeg" } ] } } ``` ### Perform Follow-Up Action Create or update a follow-up issue linked to an existing issue. The mutation finds an original issue using filters and creates a follow-up with the specified form data. Subsequent calls with the same `triggerContextReference` update the existing follow-up rather than creating duplicates. ```graphql theme={null} mutation PerformIssueFollowUpAction($input: PerformIssueFollowUpActionInput!) { performIssueFollowUpAction(input: $input) { issue { id title status } correlationId } } ``` **Variables:** ```json theme={null} { "input": { "subjectFormReference": "leak", "triggerContextReference": "external-id-123", "filters": [ { "field": "work_order_number", "operator": "EQUAL", "value": "external-id-123" } ], "followUpFormReference": "leak-repair", "followUpTaskTitle": "Leak Repair Required", "followUpTaskDescription": "Repair leak identified in work order external-id-123", "followUpFormData": { "technician_name": "John Smith", "repairDate": "2025-01-01T00:00:00.000Z" } } } ``` ### Delete Issue Deletes an issue. Assets and statuses associated with the issue are not affected. ```graphql theme={null} mutation DeleteIssue($input: DeleteIssueInput!) { deleteIssue(input: $input) { issue { id title } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "issueId": "issue-123" } } ``` ## Multi-Task Management Multi-tasks enable coordinated campaigns across multiple locations or assets. ### Create Multi-Task ```graphql theme={null} mutation CreateMultiTask($input: CreateIssueInput!) { createIssue(input: $input) { issue { id title type status } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "title": "Q4 2025 Site-Wide Inspection", "description": "Quarterly inspection of all wells at North Field", "type": "MULTITASK", "severity": "HIGH", "dueAt": "2025-12-31T23:59:59Z" } } ``` ### Create Subtasks ```graphql theme={null} mutation CreateSubtask($input: CreateIssueInput!) { createIssue(input: $input) { issue { id title type parentTask { id title } } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "title": "Inspect Well ABC-123", "type": "SUBTASK", "parentTaskId": "multitask-456", "subject": { "type": "ASSET", "reference": "well-abc-123" }, "assignee": { "userId": "field-tech-001" } } } ``` ### Query Multi-Task with Subtasks ```graphql theme={null} query GetMultiTaskWithSubtasks($id: ID!) { issues { byId(id: $id) { id title type status subtasks { id title status assignee { username } subject { type reference } } } } } ``` ## XForms for Data Collection ### Query Available Forms ```graphql theme={null} query GetForms { forms { all(first: 100) { edges { node { formId title version description xformDetails { model binds { nodeset type required readonly } body { ... on XFormBodyControlNode { id control label hint ref } ... on XFormBodyGroupNode { id label childNodeIds } } } } } } } } ``` ### Get Specific Form ```graphql theme={null} query GetForm($formId: ID!) { forms { byId(id: $formId) { formId title version description xformDetails { model binds { nodeset type required relevant constraint calculate } body { __typename ... on XFormBodyControlNode { id control label hint items { label value } } ... on XFormBodyGroupNode { id label childNodeIds } ... on XFormBodyRepeatNode { id label ref childNodeIds } } } } } } ``` ### Submit Form Response ```graphql theme={null} mutation SubmitFormResponse($input: CreateFormResponseInput!) { createFormResponse(input: $input) { formResponse { responseId formId submittedAt submittedBy { username } data } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "formId": "well-inspection-form", "issueId": "issue-123", "data": { "inspector": "John Smith", "inspectionDate": "2025-11-05", "wellCondition": "good", "pressureReading": "850", "temperatureReading": "72", "notes": "No issues observed", "photos": [ "https://storage.example.com/photo1.jpg", "https://storage.example.com/photo2.jpg" ] } } } ``` ### Link Form to Task ```graphql theme={null} mutation LinkFormToTask($input: LinkFormToIssueInput!) { linkFormToIssue(input: $input) { issue { id xform { formId responseId status } } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "issueId": "issue-123", "formId": "well-inspection-form" } } ``` ## Workflows ### Query Workflow Definition ```graphql theme={null} query GetWorkflow($workflowId: ID!) { workflow(id: $workflowId) { id name description states { id name isInitial isFinal } transitions { from to event guards { condition message } } } } ``` ### Trigger Workflow Transition ```graphql theme={null} mutation TransitionIssue($input: TransitionIssueInput!) { transitionIssue(input: $input) { issue { id status workflow { currentState availableTransitions { event to } } } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "issueId": "issue-123", "event": "complete_inspection" } } ``` ## Common Workflows ### Mobile Inspection Workflow 1. **Create Task** with asset subject and XForm 2. **Assign** to field technician 3. **Technician opens** task in mobile app 4. **Complete XForm** with inspection data 5. **Submit** form response 6. **Update task** status to RESOLVED 7. **Supervisor reviews** and CLOSES task ```javascript theme={null} // Example mobile inspection flow async function mobileInspectionWorkflow(assetId, formId, technicianId) { // 1. Create task const { data: taskData } = await createIssue({ title: `Inspect Asset ${assetId}`, type: 'TASK', subject: { type: 'ASSET', reference: assetId }, assignee: { userId: technicianId } }) const taskId = taskData.createIssue.issue.id // 2. Link form to task await linkFormToIssue({ issueId: taskId, formId: formId }) // 3. Technician completes form const formData = await collectDataInMobileApp() // 4. Submit form response await createFormResponse({ formId: formId, issueId: taskId, data: formData }) // 5. Update task status await updateIssue({ id: taskId, status: 'RESOLVED' }) return taskId } ``` ### Multi-Task Campaign Workflow 1. **Create multi-task** for campaign 2. **Generate subtasks** for each location 3. **Assign subtasks** to field teams 4. **Track completion** of individual subtasks 5. **Multi-task auto-completes** when all subtasks done ```javascript theme={null} // Example multi-task campaign async function createInspectionCampaign(assets, formId) { // 1. Create multi-task const { data: multiTaskData } = await createIssue({ title: 'Q4 Inspection Campaign', type: 'MULTITASK', dueAt: '2025-12-31T23:59:59Z' }) const multiTaskId = multiTaskData.createIssue.issue.id // 2. Create subtask for each asset for (const asset of assets) { await createIssue({ title: `Inspect ${asset.displayName}`, type: 'SUBTASK', parentTaskId: multiTaskId, subject: { type: 'ASSET', reference: asset.id }, assignee: { userId: asset.assignedTech } }) } return multiTaskId } ``` ## Issue Templates ### Create Issue Template ```graphql theme={null} mutation CreateIssueTemplate($input: CreateIssueTemplateInput!) { createIssueTemplate(input: $input) { template { id name title description type defaultSeverity defaultFormId } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "name": "quarterly-well-inspection", "title": "Quarterly Well Inspection", "description": "Standard quarterly inspection procedure", "type": "TASK", "defaultSeverity": "MEDIUM", "defaultFormId": "well-inspection-form" } } ``` ### Create Issue from Template ```graphql theme={null} mutation CreateIssueFromTemplate($input: CreateIssueFromTemplateInput!) { createIssueFromTemplate(input: $input) { issue { id title type xform { formId } } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "templateId": "quarterly-well-inspection", "subject": { "type": "ASSET", "reference": "well-abc-123" }, "assignee": { "userId": "tech-001" }, "dueAt": "2025-12-15T23:59:59Z" } } ``` ## Asset Filters Create reusable filters for finding form subjects: ### Create Asset Filter ```graphql theme={null} mutation CreateAssetFilter($input: CreateAssetFilterInput!) { createAssetFilter(input: $input) { assetFilter { id displayName profile filterString } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "id": "active-wells-north-field", "displayName": "Active Wells - North Field", "profile": "well-inspection", "subProfiles": [], "filterString": "properties.status = 'active' AND properties.field = 'north'" } } ``` ### Query Assets with Filter ```graphql theme={null} query GetFilteredAssets($profile: ID!, $filterId: ID!) { assets(profile: $profile) { filtered(filter: $filterId, first: 100) { edges { node { id displayName properties } } } } } ``` ## Best Practices ### 1. Use Asset Profiles for Form Subjects Define asset profiles for entities that field teams will work on: ```graphql theme={null} # Good - dedicated profile for inspection subjects assetProfiles { byId(profile: "equipment-inspection") } # Avoid - mixing operational assets with form subjects # Use CAM assets for operational data, FSM asset profiles for forms ``` ### 2. Link Forms to Tasks Always link XForms to tasks for proper tracking: ```graphql theme={null} # Good - form linked to task linkFormToIssue(input: { issueId: "task-123", formId: "inspection-form" }) # Incomplete - orphaned form response createFormResponse(input: { formId: "inspection-form", data: {...} }) ``` ### 3. Use Multi-Tasks for Campaigns For coordinated work across multiple locations, use multi-tasks: ```graphql theme={null} # Good - multi-task with subtasks createIssue(type: "MULTITASK") → createIssue(type: "SUBTASK", parentTaskId: "...") # Less organized - individual unrelated tasks createIssue(type: "TASK") + createIssue(type: "TASK") + ... ``` ### 4. Leverage Templates Create templates for recurring workflows: ```graphql theme={null} # Good - consistent task creation createIssueFromTemplate(templateId: "monthly-inspection") # More work - manual task creation each time createIssue(title: "...", description: "...", formId: "...") ``` ### 5. Filter by Status for Work Queues Query issues by status to create work queues: ```graphql theme={null} # Active work queue issues { all(filter: { status: ["OPEN", "IN_PROGRESS"] }) } # Completed work issues { all(filter: { status: ["RESOLVED", "CLOSED"] }) } ``` ## Error Handling FSM mutations return errors in the standard format: ```json theme={null} { "data": { "createIssue": { "issue": null, "correlationId": "abc-123", "errors": [ { "message": "Subject asset 'well-xyz' not found", "type": "INVALID_SUBJECT" } ] } } } ``` Common error types: * `INVALID_SUBJECT`: Referenced subject does not exist * `INVALID_ASSIGNEE`: Assignee user not found * `INVALID_FORM`: Form ID does not exist * `INVALID_STATUS_TRANSITION`: Status change not allowed * `MISSING_REQUIRED`: Required field not provided * `DUPLICATE_ID`: ID already exists ## Related Resources * **[Issues Subgraph Reference](../subgraphs/issues)** - Complete issue schema * **[Workflow Subgraph Reference](../subgraphs/workflow)** - Workflow definitions * **[Forms Subgraph Reference](../subgraphs/forms)** - XForms schema * **[Assets Subgraph Reference](../subgraphs/assets)** - Asset profiles schema * **[CAM Guide](./cam-assets)** - Connected asset management (different from FSM assets) * **[Common Patterns](../common-patterns)** - Pagination and filtering # GraphQL API Overview Source: https://docs.sensorup.com/api/graphql/overview Introduction to the SensorUp federated GraphQL API, architecture, and available endpoints across multiple environments. # GraphQL API Overview The SensorUp platform provides a comprehensive GraphQL API built on Apollo Federation, allowing you to query and manipulate data across assets, emissions, issues, workflows, and more through a unified graph interface. ## Architecture The SensorUp GraphQL API uses **Apollo Federation v2.3** to compose 15 specialized subgraphs into a single, unified API. This architecture enables: * **Domain separation**: Each subgraph owns a specific business domain * **Independent deployment**: Subgraphs can be updated independently * **Type composition**: Entities can be extended across multiple subgraphs * **Optimized queries**: The gateway intelligently routes and batches requests ### Subgraphs by Domain | Domain | Subgraphs | Purpose | | - | - | - | | **Connected Asset Management (CAM)** | su-cam-assets | Asset types, properties, and hierarchy for connected operations | | **Field Service Management** | su-assets, su-issues, su-workflow, su-forms | Form subjects for mobile workflows, issue tracking, workflow orchestration | | **Emissions/LDAR** | su-methane-ldar-backend, su-methane-reconcile-backend, su-detections-ingress | LDAR operations, reconciliation, detection ingestion | | **Core Platform** | su-backend, su-auth, su-user, su-maps, su-catalog, su-eventhub | Authentication, user management, geospatial services, catalogs, events, core infrastructure | | **Deprecated** | su-sites | Site management (deprecated - use su-maps for geospatial features) | ## Available Environments The GraphQL API is available in multiple environments: | Environment | Gateway URL | Purpose | | - | - | - | | **Demo** | `https://customer-demo.sensorup.com/api/graphql` | Demo and POC environment | | **Staging** | Contact your account team | Pre-production testing | | **Production** | Contact your account team | Production workloads | Staging and production URLs are tenant-specific. Contact your SensorUp account team for your organization's endpoints. ## API Capabilities ### Queries * Asset management and profiles * Emission observations and LDAR workflows * Issue tracking and templates * Site and geospatial data * User and authentication information * Workflow definitions and tasks * Dynamic forms and catalogs ### Mutations * Create and update assets * Manage emission events and observations * Create and modify issues * Update workflow states * User authentication and session management * Configure asset profiles and views ### Common Features * **Relay-style pagination**: Cursor-based pagination with `edges`, `nodes`, and `PageInfo` * **GeoJSON support**: Full GeoJSON type system for geospatial data * **Audit trails**: Automatic tracking of creation and modification metadata * **Error handling**: Consistent `MutationError` interface across all mutations * **Entity references**: Cross-subgraph entity resolution via Apollo Federation ## Getting Started 1. **[Quickstart Guide](./quickstart)** - Make your first GraphQL query 2. **[Authentication](./authentication)** - Learn how to authenticate API requests 3. **[Common Patterns](./common-patterns)** - Understand pagination, filtering, and error handling 4. **[Domain Guides](./guides/cam-assets)** - Explore specific use cases by domain: * [Connected Asset Management](./guides/cam-assets) - Asset types, properties, and hierarchy * [Field Service Management](./guides/field-service) - Mobile workflows and issue tracking * [Emissions & LDAR](./guides/emissions) - Methane detection and compliance * [Core Platform](./guides/core-platform) - Authentication, maps, and infrastructure ## GraphQL Tools You can interact with the API using: * **Apollo Explorer** (Recommended): Built-in interactive explorer available as an application plugin * Demo environment: `https://customer-demo.sensorup.com/plugins/sr/apolloGraphql` * Authentication handled automatically when accessed within the application * Full schema documentation, query building, and testing capabilities * **Apollo Studio**: View the federated schema and query planning (requires credentials) * Access at: [https://studio.apollographql.com/graph/su-graphql-t912yf/](https://studio.apollographql.com/graph/su-graphql-t912yf/) * **HTTP Clients**: Any GraphQL client library (Apollo Client, urql, graphql-request, etc.) * **curl**: Direct HTTP requests to the gateway endpoint ## Schema Reference For detailed type definitions and technical reference: * **[Subgraph Reference](./subgraphs/assets)** - Full schema documentation for each subgraph * **[Raw SDL Files](./schemas/sdl/)** - GraphQL schema definition language files * **[Federation Concepts](./federation)** - Understanding entity composition across subgraphs ## Support Need help with the GraphQL API? * Review the [Domain Guides](./guides/cam-assets) for common use cases * Check the [Common Patterns](./common-patterns) for best practices * Contact your SensorUp account team for technical support # Performance & Best Practices Source: https://docs.sensorup.com/api/graphql/performance Learn how to optimize GraphQL queries, improve performance, and follow best practices for the SensorUp API. # Performance & Best Practices This guide covers strategies for optimizing your use of the SensorUp GraphQL API to achieve the best performance and reliability. ## Query Optimization ### Request Only What You Need GraphQL's strength is precise field selection. Use it: **Bad:** ```graphql theme={null} query { assets { all(first: 100) { edges { node { id profile displayName secondaryDisplayName modifiedAt geometry { type coordinates bbox } properties # Potentially large! observation # Very large! geoJSONFeature # Redundant with above related # Expensive! } } } } } ``` **Good:** ```graphql theme={null} query { assets { all(first: 100) { edges { node { id displayName modifiedAt } } } } } ``` **Impact**: Reduced payload size by 90%+, faster response times ### Use Pagination Appropriately Don't request more data than you can display: **Bad:** ```graphql theme={null} query { assets { all(first: 10000) { # Too many! edges { node { id displayName } } } } } ``` **Good:** ```graphql theme={null} query { assets { all(first: 20) { # One page edges { node { id displayName } } pageInfo { hasNextPage endCursor } } } } ``` **Recommended page sizes**: * UI lists: 20-50 items * Background processing: 100-500 items * Exports: Use export endpoints, not pagination ### Batch Related Queries GraphQL allows querying multiple resources in one request: **Bad:** ```javascript theme={null} // 3 separate requests const session = await getSession() const assets = await getAssets() const issues = await getIssues() ``` **Good:** ```javascript theme={null} // 1 request const result = await query(` query { session { username authenticated } assetProfiles { all(first: 20) { edges { node { profile title } } } } issues { all(first: 20) { edges { node { id title } } } } } `) ``` **Impact**: Reduced latency by \~66%, fewer round trips ### Use Fragments for Reusability Define reusable fragments for common field sets: ```graphql theme={null} fragment AssetSummary on Asset { id displayName modifiedAt geometry { type coordinates } } fragment IssueSummary on Issue { id title status severity dueAt } query GetData { assets { all(first: 20) { edges { node { ...AssetSummary } } } } issues { all(first: 20) { edges { node { ...IssueSummary } } } } } ``` ## Federation Performance ### Understand Query Plans Cross-subgraph queries require multiple fetches. Minimize hops: **Less Efficient:** ```graphql theme={null} query { issues { all(first: 100) { edges { node { subject { assetReference { # Fetch from su-assets (100 times) asset { displayName assetProfile { # Another fetch (100 times) title } } } } } } } } } ``` **More Efficient:** ```graphql theme={null} query { issues { all(first: 100) { edges { node { id title status } } } } } // If you need asset details, fetch them separately with specific IDs ``` ### Leverage Parallel Execution Federation executes independent root fields in parallel: ```graphql theme={null} query { session { # su-auth - parallel username } assetProfiles { # su-assets - parallel all(first: 10) { edges { node { title } } } } issues { # su-issues - parallel all(first: 10) { edges { node { title } } } } } ``` All three subgraphs are queried simultaneously. ## Filtering & Searching ### Use Server-Side Filtering Filter on the server, not the client: **Bad:** ```javascript theme={null} // Fetch everything, filter client-side const all = await getAssets({ first: 1000 }) const filtered = all.filter(a => a.modifiedAt > cutoff) ``` **Good:** ```javascript theme={null} // Filter server-side const filtered = await getAssets({ first: 100, filter: { modifiedAfter: cutoff } }) ``` ### Specific Lookups vs. List Filtering Use ID lookups when you know the ID: **Less Efficient:** ```graphql theme={null} query { assets { all(first: 1000, filter: { id: "asset-123" }) { edges { node { id displayName } } } } } ``` **More Efficient:** ```graphql theme={null} query { assetProfiles { byId(profile: "wells") { assetById(id: "asset-123") { id displayName } } } } ``` ## Caching Strategies ### Cache Static Data Some data changes infrequently: | Data Type | Change Frequency | Cache Duration | | - | - | - | | Asset Profiles | Rarely | 1 hour - 1 day | | Catalog Entries | Rarely | 1 day - 1 week | | Form Templates | Occasionally | 1 hour | | Map Configurations | Rarely | 1 day | | User Session | Often | No cache (always fetch) | | Assets | Often | No cache or short (5 min) | ### HTTP Caching Configure appropriate cache headers: ```javascript theme={null} const response = await fetch(url, { headers: { 'Cache-Control': 'max-age=300' // 5 minutes } }) ``` ### Application-Level Caching Use a caching client like Apollo Client: ```javascript theme={null} import { ApolloClient, InMemoryCache } from '@apollo/client' const client = new ApolloClient({ uri: 'https://customer-demo.sensorup.com/api/graphql', cache: new InMemoryCache({ typePolicies: { AssetProfile: { keyFields: ['profile'] }, Asset: { keyFields: ['profile', 'id'] } } }) }) ``` ## Rate Limiting & Throttling ### Implement Exponential Backoff When encountering rate limits or errors: ```javascript theme={null} async function fetchWithRetry(query, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { return await fetch(query) } catch (error) { if (i === maxRetries - 1) throw error const delay = Math.min(1000 * Math.pow(2, i), 10000) await new Promise(resolve => setTimeout(resolve, delay)) } } } ``` ### Batch Updates Instead of many small mutations, batch when possible: **Less Efficient:** ```javascript theme={null} for (const issue of issues) { await updateIssue(issue.id, { status: 'CLOSED' }) } ``` **More Efficient:** ```javascript theme={null} await bulkUpdateIssues({ filter: { issueIds: issues.map(i => i.id) }, updates: { status: 'CLOSED' } }) ``` ## Query Complexity ### Avoid Deep Nesting Deep queries can be expensive: **High Complexity:** ```graphql theme={null} query { sites { all { assets { all { issueSubject { issues { all { annotations { all { # Very expensive! } } } } } } } } } } ``` **Lower Complexity:** ```graphql theme={null} query { sites { all(first: 20) { edges { node { id name } } } } } # Then fetch assets for specific sites # Then fetch issues for specific assets ``` ### Limit List Sizes Always use pagination limits: ```graphql theme={null} query { assets { all(first: 20) { # Always specify! edges { node { id } } } } } ``` ## Monitoring & Debugging ### Use Correlation IDs Include correlation IDs for tracking: ```javascript theme={null} const correlationId = uuid() await mutation({ variables: { input: { ... }, correlationId } }) console.log(`Request ID: ${correlationId}`) ``` ### Log Query Performance Track slow queries: ```javascript theme={null} const start = Date.now() const result = await client.query({ query }) const duration = Date.now() - start if (duration > 1000) { console.warn(`Slow query: ${duration}ms`, query) } ``` ### Monitor Error Rates Track and alert on error patterns: ```javascript theme={null} let errorCount = 0 let requestCount = 0 try { await query() requestCount++ } catch (error) { errorCount++ requestCount++ const errorRate = errorCount / requestCount if (errorRate > 0.05) { alert('High error rate detected!') } } ``` ## Network Optimization ### Use Compression Enable gzip/brotli compression: ```javascript theme={null} fetch(url, { headers: { 'Accept-Encoding': 'gzip, deflate, br' } }) ``` ### Minimize Payload Size * Use fragments to avoid duplication * Omit `__typename` if not needed * Use aliases to simplify response structure ### Connection Pooling Reuse HTTP connections: ```javascript theme={null} const agent = new http.Agent({ keepAlive: true, maxSockets: 50 }) fetch(url, { agent }) ``` ## Best Practices Checklist ### Query Design * [ ] Request only needed fields * [ ] Use pagination (first: 20-100) * [ ] Apply server-side filters * [ ] Use specific lookups vs. list queries * [ ] Batch related queries in one request * [ ] Use fragments for reusability ### Performance * [ ] Cache static data (profiles, catalogs) * [ ] Implement exponential backoff * [ ] Monitor query performance * [ ] Use correlation IDs * [ ] Minimize cross-subgraph hops * [ ] Limit query depth (≤ 4 levels) ### Error Handling * [ ] Check GraphQL-level errors * [ ] Check mutation-level errors * [ ] Log errors with context * [ ] Implement retry logic * [ ] Handle partial failures gracefully ### Security * [ ] Store credentials securely * [ ] Rotate API keys regularly * [ ] Use HTTPS always * [ ] Validate input data * [ ] Sanitize user-provided content ## Performance Metrics ### Target Metrics | Metric | Target | Good | Needs Improvement | | - | - | - | - | | Query latency (p50) | \< 200ms | \< 500ms | > 500ms | | Query latency (p99) | \< 1s | \< 2s | > 2s | | Error rate | \< 0.1% | \< 1% | > 1% | | Cache hit rate | > 80% | > 60% | \< 60% | ### Measuring Performance ```javascript theme={null} const metrics = { queryCount: 0, errorCount: 0, totalDuration: 0, cacheHits: 0 } function recordQuery(duration, fromCache, error) { metrics.queryCount++ metrics.totalDuration += duration if (fromCache) metrics.cacheHits++ if (error) metrics.errorCount++ } function getMetrics() { return { avgDuration: metrics.totalDuration / metrics.queryCount, errorRate: metrics.errorCount / metrics.queryCount, cacheHitRate: metrics.cacheHits / metrics.queryCount } } ``` ## Common Anti-Patterns ### 1. Over-fetching ```graphql theme={null} # Don't fetch everything "just in case" query { assets { all(first: 100) { edges { node { # Every possible field... } } } } } ``` ### 2. N+1 in Application Code ```javascript theme={null} // Don't do this! const issues = await getIssues() for (const issue of issues) { const asset = await getAsset(issue.assetId) // N queries! } ``` ### 3. Polling Too Frequently ```javascript theme={null} // Don't poll every second! setInterval(async () => { await fetchData() }, 1000) // Use reasonable intervals setInterval(async () => { await fetchData() }, 30000) // 30 seconds ``` ### 4. Ignoring Errors ```javascript theme={null} // Don't ignore errors! try { await mutation() } catch (e) { // Silence! } // Handle them properly try { await mutation() } catch (error) { console.error('Mutation failed:', error) showErrorToUser(error.message) reportToMonitoring(error) } ``` ## Resources * **[Federation Concepts](./federation)** - Understanding query planning * **[Common Patterns](./common-patterns)** - API patterns and conventions * **[Apollo Client Performance](https://www.apollographql.com/docs/react/performance/performance/)** - Client-side optimization * **[GraphQL Best Practices](https://graphql.org/learn/best-practices/)** - General GraphQL guidelines ## Support For performance issues or optimization assistance: * Review query plans in Apollo Studio * Contact your SensorUp account team * Provide correlation IDs for specific slow queries # GraphQL API Quickstart Source: https://docs.sensorup.com/api/graphql/quickstart Get started with the SensorUp GraphQL API - make your first query and learn the basics. # GraphQL API Quickstart This guide will help you make your first GraphQL query to the SensorUp API and understand the basics of working with the federated graph. ## Prerequisites Before you begin, you'll need: * Access to a SensorUp environment (demo, staging, or production) * Valid authentication credentials (see [Authentication](./authentication)) * A GraphQL client or HTTP tool (curl, Postman, or a programming language client) ## Your First Query ### Using curl ```bash theme={null} curl -X POST https://customer-demo.sensorup.com/api/graphql \ -H "Content-Type: application/json" \ -H "x-sensorup-sessionid: YOUR_SESSION_ID" \ -d '{ "query": "query { session { username authenticated } }" }' ``` ### Response ```json theme={null} { "data": { "session": { "username": "your-username", "authenticated": true } } } ``` ## Understanding the Query Structure GraphQL queries have three main components: ```graphql theme={null} query { # Operation type (query, mutation, or subscription) session { # Root field - what you're querying username # Selection - fields you want returned authenticated } } ``` ## Common Query Patterns ### Querying Asset Profiles ```graphql theme={null} query GetAssetProfiles { assetProfiles { all(first: 10) { edges { node { profile title displayNameProperty } } pageInfo { hasNextPage endCursor } } } } ``` ### Getting Specific Asset by ID ```graphql theme={null} query GetAsset($profileId: ID!, $assetId: ID!) { assetProfiles { byId(profile: $profileId) { profile title assetById(id: $assetId) { id displayName properties geometry } } } } ``` **Variables:** ```json theme={null} { "profileId": "your-profile-id", "assetId": "your-asset-id" } ``` ### Querying Issues ```graphql theme={null} query GetIssues { issues { all(first: 10) { edges { node { id displayName status createdAt audit { createdBy { userId } } } } } } } ``` ## Making Mutations Mutations modify data on the server. All mutations follow a consistent pattern with result types that include `correlationId` and `errors`. ### Creating an Asset Filter ```graphql theme={null} mutation CreateAssetFilter($input: CreateAssetFilterInput!) { createAssetFilter(input: $input) { assetFilter { id displayName profile } correlationId errors { message type } } } ``` **Variables:** ```json theme={null} { "input": { "id": "my-filter-id", "displayName": "My Asset Filter", "profile": "asset-profile-id", "subProfiles": [] } } ``` ## Pagination The API uses Relay-style cursor-based pagination: ```graphql theme={null} query PaginatedAssets($first: Int!, $after: String) { assetProfiles { byId(profile: "your-profile") { assets(first: $first, after: $after) { edges { node { id displayName } } pageInfo { hasNextPage hasPreviousPage startCursor endCursor } } } } } ``` **First page:** ```json theme={null} { "first": 10 } ``` **Next page:** ```json theme={null} { "first": 10, "after": "cursor-from-previous-page" } ``` ## Error Handling ### Query Errors GraphQL returns errors in the `errors` array: ```json theme={null} { "errors": [ { "message": "Cannot query field 'invalidField' on type 'Asset'", "locations": [{ "line": 3, "column": 5 }] } ] } ``` ### Mutation Errors Mutations return errors in the result type: ```json theme={null} { "data": { "createAssetFilter": { "assetFilter": null, "correlationId": "abc-123", "errors": [ { "message": "Asset filter with this ID already exists", "type": "DUPLICATE_ID" } ] } } } ``` ## Using GraphQL Clients ### JavaScript/TypeScript ```javascript theme={null} // Using graphql-request import { request, gql } from 'graphql-request' const query = gql` query { session { username authenticated } } ` const data = await request( 'https://customer-demo.sensorup.com/api/graphql', query, {}, { 'x-sensorup-sessionid': sessionId } ) ``` ### Python ```python theme={null} # Using gql from gql import gql, Client from gql.transport.requests import RequestsHTTPTransport transport = RequestsHTTPTransport( url='https://customer-demo.sensorup.com/api/graphql', headers={'x-sensorup-sessionid': session_id} ) client = Client(transport=transport, fetch_schema_from_transport=True) query = gql(""" query { session { username authenticated } } """) result = client.execute(query) ``` ## Next Steps Now that you've made your first queries: 1. **[Authentication](./authentication)** - Learn about auth methods and credential management 2. **[Common Patterns](./common-patterns)** - Deep dive into pagination, filtering, and GeoJSON 3. **Domain Guides** - Explore specific use cases: * [Assets](./guides/cam-assets) - Asset management * [Field Service Management](./guides/field-service) - Issues, workflows, and mobile tasks * [Emissions](./guides/emissions) - LDAR operations * [Core Platform](./guides/core-platform) - Authentication, users, and platform services 4. **Subgraph Reference** - Complete schema documentation: * [Assets](./subgraphs/assets) - Asset profiles for field service * [CAM Assets](./subgraphs/cam-assets) - Connected asset management * [Issues](./subgraphs/issues) - Issue tracking * [Forms](./subgraphs/forms) - XForms data collection * [Auth](./subgraphs/auth) - Authentication and sessions * [Workflow](./subgraphs/workflow) - Workflow definitions * And more in the subgraphs directory ## Interactive Exploration ### Apollo Explorer (Recommended) SensorUp includes Apollo Explorer as a built-in plugin for interactive query building and schema exploration: **Demo Environment:** ``` https://customer-demo.sensorup.com/plugins/sr/apolloGraphql ``` **Features:** * Interactive query builder with autocomplete * Full schema documentation browser * Query history and saved queries * Authentication handled automatically (no need to manually set headers) * Real-time query validation **For other environments:** * Replace `customer-demo.sensorup.com` with your environment's hostname * The plugin path remains `/plugins/sr/apolloGraphql` ### Additional Resources For further exploration tools, contact your SensorUp account team about: * Apollo Studio access for advanced query planning and performance monitoring * Postman collections with example queries # Assets Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/assets Technical reference for the su-assets subgraph schema, types, queries, and mutations. # Assets Subgraph Reference The `su-assets` subgraph provides comprehensive asset management capabilities including asset profiles, properties, relationships, and views. ## Subgraph Information * **Name**: `su-assets` * **Routing URL**: `https://73qfchk50k.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2025-10-09 * **SDL**: [View Schema](../schemas/sdl/su-assets.graphql) ## Overview This subgraph owns: * Asset profiles and their configuration * Individual assets and their properties * Asset relationships and hierarchies * View configurations for UI rendering * Asset filters for workflow integration * Asset conversion configurations ## Root Types ### Query Fields ```graphql theme={null} extend type Query { assetProfiles: AssetProfiles assets(profile: ID!): Assets assetFilters: [AssetSelectionFilter!] assetFilter(id: ID!): AssetSelectionFilter assetFilterDownloads: [AssetDownload!] } ``` ### Mutation Fields ```graphql theme={null} extend type Mutation { updateAssetProfile(input: UpdateAssetProfileInput): AssetProfileMutationResult putAssetProfileExtension(input: putAssetProfileExtensionInput!): AssetProfileMutationResult removeAssetProfileExtension(input: removeAssetProfileExtensionInput!): AssetProfileMutationResult updateAssetProfileViewConfiguration(input: UpdateAssetProfileViewConfigurationInput!): AssetProfileViewConfigurationMutationResult! updateAssetProfileViewLayout(input: UpdateAssetProfileViewLayoutInput): AssetProfileViewLayoutMutationResult! updateAssetProfileAssetConversionConfiguration(input: UpdateAssetProfileAssetConversionConfigurationInput!): AssetProfileAssetConversionConfigurationMutationResult! createAssetFilter(input: CreateAssetFilterInput!, correlationId: String): AssetFilterMutationResult updateAssetFilter(input: UpdateAssetFilterInput!, correlationId: String): AssetFilterMutationResult } ``` ## Core Types ### AssetProfile Defines the structure and behavior of a class of assets. ```graphql theme={null} type AssetProfile @key(fields: "profile") { profile: ID! title: String! owner: EntityOwner! properties: [AssetPropertyDefinition!] propertyMaps: [AssetProfilePropertyMapping!] displayNameProperty: String! displayNameTemplate: String secondaryDisplayNameProperty: String isDeletedProperty: String forceAssetStateUpdates: Boolean relationships: [AssetProfileRelationship!] assets(first: Int, after: String, filter: AssetFilter): AssetsConnection assetsExport(...): AssetProfileAssetExport assetById(id: ID!): Asset upDatasets: [UpDataset!] upDataset(dataset: String!): UpDataset viewConfigurations: [AssetProfileViewConfiguration!] viewConfiguration(id: ID!): AssetProfileViewConfiguration assetConversionConfigurations: [AssetProfileAssetConversionConfiguration!] stateUpdateDatasets: [StateUpdateDataset!] } ``` **Key Fields:** * `profile`: Unique identifier for this asset profile type * `title`: Human-readable name * `displayNameProperty`: Property used for asset display name * `properties`: Effective properties available on assets * `relationships`: Defined relationships to other asset profiles ### Asset Individual asset instance. ```graphql theme={null} type Asset @key(fields: "profile id") { id: ID! profile: ID! assetProfile: AssetProfile modifiedAt: DateTime geometry: GeoJSONGeometryInterface properties(only: [String!]): JSONObject observation: JSONObject geoJSONFeature: GeoJSONFeature displayName: String! secondaryDisplayName: String related(relationship: ID, params: JSONObject): AssetRelationship issueSubject: IssueSubject! isDeleted: Boolean! } ``` **Key Fields:** * `id`: Unique asset identifier within profile * `profile`: Reference to asset profile * `displayName`: Computed display name from profile configuration * `properties`: Dynamic properties from underlying datasets * `observation`: Merged state observation * `geometry`: GeoJSON geometry if geospatial * `related`: Navigate relationships to other assets ### AssetRelationship Union type for one-to-one or one-to-many relationships. ```graphql theme={null} union AssetRelationship = AssetRelationshipOne | AssetRelationshipMany type AssetRelationshipOne { asset: Asset observation: JSONObject } type AssetRelationshipMany { assets: [Asset!] observations: [JSONObject!] } ``` ### AssetProfileRelationship Defines a relationship between asset profiles. ```graphql theme={null} type AssetProfileRelationship { relationship: ID! type: AssetProfileRelationshipType! # ONE or MANY profile: ID! assetProfile: AssetProfile! referenceProperty: String referenceType: AssetProfileRelationshipReferenceType! lookupProperty: String lookupType: AssetProfileRelationshipReferenceType! parameters: [UpSpecificationParameter!] } ``` ## Pagination Uses Relay-style cursor pagination: ```graphql theme={null} type AssetsConnection { pageInfo: PageInfo! edges: [AssetEdge] } type AssetEdge { node: Asset } ``` ## View Configurations UI layout and visualization settings: ```graphql theme={null} type AssetProfileViewConfiguration { id: ID! name: String map: AssetProfileViewMap layouts(mediaTypes: [AssetProfileViewLayoutMediaType!]): [AssetProfileViewLayout!] } type AssetProfileViewLayout { mediaType: AssetProfileViewLayoutMediaType # WEB, MOBILE, PRINTABLE widgets: [AssetProfileViewWidget!] } type AssetProfileViewWidget { id: ID! layout: AssetProfileViewLayoutDetails! # x, y, w, h name: String! settings: JSONObject! widget: String! } ``` ## Asset Filters Reusable asset selections for workflows: ```graphql theme={null} type AssetSelectionFilter @key(fields: "id") { id: ID! displayName: String! description: String profile: ID! assetProfile: AssetProfile! subProfiles: [AssetSelectionFilterRelationship!] audit: AssetSelectionFilterAudit } ``` ## Entity Extensions This subgraph extends entities from other subgraphs: ### EntityOwner ```graphql theme={null} type EntityOwner @extends @key(fields: "username group") { username: String! @external group: String! @external } ``` ### IssueSubject ```graphql theme={null} type IssueSubject @extends @key(fields: "type reference") { type: String! @external reference: ID! @external assetReference: AssetReference @requires(fields: "type reference") } ``` ## Common Patterns ### Query Assets with Pagination ```graphql theme={null} query GetAssets($profile: ID!, $first: Int!, $after: String) { assetProfiles { byId(profile: $profile) { assets(first: $first, after: $after) { edges { node { id displayName modifiedAt } } pageInfo { hasNextPage endCursor } } } } } ``` ### Update Asset Profile ```graphql theme={null} mutation UpdateProfile($input: UpdateAssetProfileInput!) { updateAssetProfile(input: $input) { assetProfile { profile displayNameTemplate } correlationId errors { message type } } } ``` ### Export Assets ```graphql theme={null} query ExportAssets($profile: ID!) { assetProfiles { byId(profile: $profile) { assetsExport( properties: ["name", "status"], isExcel: false ) { csvFileDownloadUrl(exportName: "assets") } } } } ``` ## Related Resources * **[CAM Assets Subgraph](./cam-assets)** - Camera-specific assets * **[Full SDL Schema](../schemas/sdl/su-assets.graphql)** - Complete type definitions ## Type Index Key types defined in this subgraph: * `AssetProfile` - Profile definitions * `Asset` - Individual assets * `AssetPropertyDefinition` - Property schemas * `AssetRelationship` - Relationship data * `AssetProfileViewConfiguration` - UI configurations * `AssetSelectionFilter` - Reusable filters * `PageInfo` - Pagination metadata (@shareable) * GeoJSON types (@shareable) # Auth Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/auth Technical reference for the su-auth subgraph providing authentication and authorization. # Auth Subgraph Reference The `su-auth` subgraph provides authentication, authorization, and session management capabilities. ## Subgraph Information * **Name**: `su-auth` * **Routing URL**: `https://xu558bs6wi.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2025-08-15 * **SDL**: [View Schema](../schemas/sdl/su-auth.graphql) ## Overview This subgraph owns: * User authentication (sign in/out) * Session management * Multi-factor authentication (MFA) * API key generation * AWS credentials provisioning * Device management ## Root Query Fields ```graphql theme={null} extend type Query { session: AuthSession credentials(group: String): AuthCredentials config: Config signWorkatoJwtToken(customerVendorOrigin: String): String } ``` ## Root Mutation Fields ```graphql theme={null} extend type Mutation { signIn(input: AuthSignInInput!): AuthMutationResult! signOut: AuthMutationResult globalSignOut: AuthMutationResult forgotPassword(input: AuthForgotPasswordInput): AuthMutationResult forgotPasswordSubmit(input: AuthForgotPasswordSubmitInput): AuthMutationResult completeNewPassword(input: AuthCompleteNewPasswordInput): AuthMutationResult! federatedSignIn(input: AuthFederatedSignInInput!): AuthMutationResult confirmSignIn(input: AuthConfirmSignInInput): AuthConfirmSignInResult! setupTOTP: AuthTOTPMutationResult! verifyTOTPToken(input: AuthVerifyTOTPTokenInput): AuthMutationResult setSessionUserGroup(input: AuthSetSessionUserGroupInput): AuthMutationResult createAPIKey(input: AuthCreateAPIKeyInput!): AuthAPIKeyResult! reauthenticate(input: ReauthenticationInput!): AuthMutationResult! forgetDevices(input: AuthForgetSpecificDevicesInput): AuthMutationResult completeAuthChallenge(input: CompleteAuthChallengeInput!): CompleteAuthChallengeResult! generateSMSCode: AuthMutationResult verifySMSCode(input: AuthVerifySMSCodeInput): AuthMutationResult } ``` ## Core Types ### AuthSession Current authentication session information. ```graphql theme={null} type AuthSession @key(fields: "username") { username: ID! preferredMFA: AuthMFAType attributes: AuthAttributes challengeName: AuthChallengeType authenticated: Boolean! audit: Audit! expiresAt: DateTime! expiresAtHard: DateTime! userGroup: ID! publicReference: ID! lastAuthenticatedAt: DateTime } ``` ### AuthCredentials Temporary AWS credentials for accessing AWS services. ```graphql theme={null} type AuthCredentials { accessKeyId: String! secretAccessKey: String! sessionToken: String! expiration: DateTime! } ``` ### AuthDevice Registered device information. ```graphql theme={null} type AuthDevice { deviceKey: ID! name: String remembered: Boolean createdAt: DateTime modifiedAt: DateTime lastSignedInAt: DateTime lastIpAddress: String } ``` ## Entity Extensions ### User Extends User type from su-user with device information. ```graphql theme={null} type User @key(fields: "id") @extends { id: ID! @external devices: [AuthDevice!] } ``` ## Related Resources * **[Authentication Guide](../authentication)** - Authentication workflows and examples * **[Quickstart Guide](../quickstart)** - Getting started with auth * **[Full SDL Schema](../schemas/sdl/su-auth.graphql)** - Complete type definitions # Backend Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/backend Technical reference for the su-backend subgraph providing core platform services. # Backend Subgraph Reference The `su-backend` subgraph provides core backend platform services. ## Subgraph Information * **Name**: `su-backend` * **Routing URL**: `https://y5mg53yiuk.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2023-10-13 * **SDL**: [View Schema](../schemas/sdl/su-backend.graphql) ## Overview Core platform functionality and base services. ## Root Query Fields ```graphql theme={null} extend type Query { platform: Platform! } ``` ### Platform Query The `platform` query provides access to platform version information and client configuration. ## Related Resources * **[Overview](../overview)** - GraphQL API introduction * **[Full SDL Schema](../schemas/sdl/su-backend.graphql)** - Complete type definitions # CAM Assets Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/cam-assets Technical reference for the su-cam-assets subgraph providing Connected Asset Management operations including asset types, properties, and hierarchy. # CAM Assets Subgraph Reference The `su-cam-assets` subgraph provides Connected Asset Management (CAM) capabilities for managing asset types, asset properties, and asset hierarchy in connected operations. ## Subgraph Information * **Name**: `su-cam-assets` * **Routing URL**: `https://mijlot8lad.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2025-11-03 * **SDL**: [View Schema](../schemas/sdl/su-cam-assets.graphql) ## Overview CAM Assets manages the foundational structure for connected operations: * **Asset Types**: Define schemas for different kinds of operational assets * **Asset Properties**: Custom attributes and their data types * **Asset Hierarchy**: Parent-child relationships between assets * **Camera Assets**: Specialized operations for camera and detection assets * **Batch Operations**: Large-scale asset creation and updates * **Geospatial**: Full GeoJSON support for asset locations ## Key Concepts ### Asset Types Asset types define the structure and schema for operational assets: * **Properties**: Custom attributes (name, data type, required, default value) * **Extensions**: External data source integrations * **Status Tracking**: Configuration for asset state management * **Hierarchy Rules**: Parent-child relationship constraints ### Assets Assets are instances of asset types representing operational entities: * **Sites**: Top-level geographic locations * **Equipment**: Major operational assets * **Components**: Sub-components within equipment * **Wells**: Oil and gas well assets * **Pipelines**: Pipeline infrastructure ### Asset Hierarchy Assets can be organized in parent-child relationships: * Multi-level organizational structures * Inherited properties and configurations * Hierarchical queries and filtering * Geographic nesting (e.g., equipment within sites) ## Core Types ### CamAssets Main entry point for querying assets: ```graphql theme={null} type CamAssets { byId(id: ID!): CamAsset all( first: Int after: String filter: CamAssetFilter fullTextSearch: CamAssetFullTextSearch sortBy: CamAssetSortBy withExtensions: [ID] includeDelta: Boolean ): CamAssetsConnection } ``` ### CamAsset Individual asset instance: ```graphql theme={null} type CamAsset { id: ID! name: String! description: String assetTypeId: ID! active: Boolean! geometry: GeoJSONGeometry properties: JSONObject parent: CamAssetReference children: [CamAssetReference] status: CamAssetStatus extensionData: [CamAssetExtensionData] audit: AuditInfo } ``` ### AssetTypes Manage asset type definitions: ```graphql theme={null} type AssetTypes { byId(assetTypeId: ID!): AssetType all( first: Int after: String filter: AssetTypeFilter sortBy: AssetTypeSortBy ): AssetTypesConnection } ``` ### AssetType Asset type definition: ```graphql theme={null} type AssetType { assetTypeId: ID! name: String! description: String properties: [AssetTypeProperty!] extensions: [AssetTypeExtension!] parentAssetTypes: [ID!] childAssetTypes: [ID!] audit: AuditInfo } ``` ### AssetTypeProperty Property definition within an asset type: ```graphql theme={null} type AssetTypeProperty { id: ID! name: String! dataType: PropertyDataType! required: Boolean! defaultValue: String validation: PropertyValidation displayOrder: Int } ``` ## Query Operations ### camAssets Query assets by type: ```graphql theme={null} query GetAssetsByType($assetTypeId: ID!) { camAssets(assetTypeId: $assetTypeId) { all(first: 20) { edges { node { id name assetTypeId properties geometry { type coordinates } } } pageInfo { hasNextPage endCursor } } } } ``` ### assetTypes Query available asset types: ```graphql theme={null} query GetAssetTypes { assetTypes { all(first: 100) { edges { node { assetTypeId name description properties { id name dataType required } } } } } } ``` ### camAssetReferences Lightweight asset references for dropdowns: ```graphql theme={null} query GetAssetReferences { camAssetReferences { all(first: 100) { edges { node { id name assetTypeId } } } } } ``` ### camEngine Query CAM engine configuration and datasets: ```graphql theme={null} query GetCamEngine { camEngine { datasets { id name assetTypeId sourceType lastUpdated } configuration { key value } } } ``` ### camAssetsDatasets Get datasets for a specific tenant: ```graphql theme={null} query GetDatasets($group: ID!) { camAssetsDatasets(group: $group) { dataset displayName assetTypeId recordCount } } ``` ### assetConfigs Query tenant-specific configurations: ```graphql theme={null} query GetConfigs($group: ID!) { assetConfigs(group: $group) { all { id value updatedAt } } } ``` ### generateBatchUpsertUploadUrl Generate presigned S3 URL for batch operations: ```graphql theme={null} query GenerateUploadUrl($input: GenerateBatchUpsertUploadUrlInput!) { generateBatchUpsertUploadUrl(input: $input) { uploadUrl batchUpsertReference expiresAt } } ``` ### camCatalog Query catalog configuration for a group: ```graphql theme={null} query GetCatalog($group: ID!) { camCatalog(group: $group) { catalogId assetTypes { assetTypeId name } } } ``` ### assetAuditing Access audit trail information: ```graphql theme={null} query GetAssetAudit { assetAuditing { history(assetId: "asset-123") { version eventType eventTime updatedBy } } } ``` ## Mutation Operations ### createAsset Create a new asset: ```graphql theme={null} mutation CreateAsset($input: CreateAssetInput!, $correlationId: ID) { createAsset(input: $input, correlationId: $correlationId) { asset { id name assetTypeId } correlationId errors { message type } } } ``` ### updateAsset Update an existing asset: ```graphql theme={null} mutation UpdateAsset($input: UpdateAssetInput!, $correlationId: ID) { updateAsset(input: $input, correlationId: $correlationId) { asset { id name properties } correlationId errors { message type } } } ``` ### updateAssetProperty Update specific asset properties: ```graphql theme={null} mutation UpdateAssetProperty($input: UpdateAssetPropertyInput!, $correlationId: ID) { updateAssetProperty(input: $input, correlationId: $correlationId) { asset { id properties } correlationId errors { message type } } } ``` ### updateAssetGeometry Update asset geolocation: ```graphql theme={null} mutation UpdateAssetGeometry($input: UpdateAssetGeometryInput!, $correlationId: ID) { updateAssetGeometry(input: $input, correlationId: $correlationId) { asset { id geometry { type coordinates } } correlationId errors { message type } } } ``` ### createAssetStatus Create asset status record: ```graphql theme={null} mutation CreateAssetStatus($input: CreateAssetStatusInput!, $correlationId: ID) { createAssetStatus(input: $input, correlationId: $correlationId) { assetStatus { assetId statusId label setAt setBy } correlationId errors { message type } } } ``` ### manageCamAssets Batch operations for assets: ```graphql theme={null} mutation ManageAssets { manageCamAssets(dryRun: false) { batchUpsert(batchUpsertReference: "ref-from-upload") { success processedCount errors { row message } } } } ``` ### setAssetConfig Update tenant configuration: ```graphql theme={null} mutation SetConfig($group: ID!, $id: ID!, $value: JSONObject!) { setAssetConfig(group: $group, id: $id, value: $value) { config { id value } correlationId errors { message type } } } ``` ### reloadCamAssetsDatasets Reload datasets from external sources: ```graphql theme={null} mutation ReloadDatasets($group: ID!) { reloadCamAssetsDatasets(group: $group) { dataset displayName recordCount } } ``` ### updateAssetStatus Update asset status: ```graphql theme={null} mutation UpdateAssetStatus($input: UpdateAssetStatusInput!, $correlationId: ID) { updateAssetStatus(input: $input, correlationId: $correlationId) { asset { id status { statusId label } } } } ``` ### deleteAssetStatus Delete asset status record: ```graphql theme={null} mutation DeleteAssetStatus($input: DeleteAssetStatusInput!, $correlationId: ID) { deleteAssetStatus(input: $input, correlationId: $correlationId) { asset { id } } } ``` ### deleteAsset Delete an asset: ```graphql theme={null} mutation DeleteAsset($input: DeleteAssetInput!, $correlationId: ID) { deleteAsset(input: $input, correlationId: $correlationId) { correlationId } } ``` ### createAssetType Create a new asset type: ```graphql theme={null} mutation CreateAssetType($input: CreateAssetTypeInput!) { createAssetType(input: $input) { assetType { assetTypeId name } } } ``` ### updateAssetType Update an asset type: ```graphql theme={null} mutation UpdateAssetType($input: UpdateAssetTypeInput!) { updateAssetType(input: $input) { assetType { assetTypeId name } } } ``` ### activateAssetType Activate an asset type: ```graphql theme={null} mutation ActivateAssetType($input: ActivateAssetTypeInput!) { activateAssetType(input: $input) { assetType { assetTypeId active } } } ``` ### deleteAssetType Delete an asset type: ```graphql theme={null} mutation DeleteAssetType($input: DeleteAssetTypeInput!) { deleteAssetType(input: $input) { correlationId } } ``` ### flushCamStreamDatasetDelta Flush streaming dataset delta: ```graphql theme={null} mutation FlushDatasetDelta($streamDatasetId: ID!) { flushCamStreamDatasetDelta(streamDatasetId: $streamDatasetId) } ``` ### deleteAssetConfig Delete asset configuration: ```graphql theme={null} mutation DeleteAssetConfig($group: ID!, $id: ID!) { deleteAssetConfig(group: $group, id: $id) { correlationId } } ``` ## Deprecated Operations The following legacy operations are deprecated in favor of the unified `camAssets` query: * `assetSites` → Use `camAssets(assetTypeId: "site")` * `assetEquipments` → Use `camAssets(assetTypeId: "equipment")` * `assetComponents` → Use `camAssets(assetTypeId: "component")` * `assetWells` → Use `camAssets(assetTypeId: "well")` * `assetPipelines` → Use `camAssets(assetTypeId: "pipeline")` * `assetUnattributeds` → Use `camAssets` without assetTypeId filter ## Filtering and Sorting ### CamAssetFilter Filter assets by various criteria: ```graphql theme={null} input CamAssetFilter { active: Boolean assetTypeIds: [ID!] parentId: ID geometry: GeoJSONGeometryFilter properties: JSONObject extensionIds: [ID!] } ``` ### CamAssetFullTextSearch Search assets by text: ```graphql theme={null} input CamAssetFullTextSearch { text: String! fields: [String!] # Search specific fields } ``` ### CamAssetSortBy Sort asset results: ```graphql theme={null} input CamAssetSortBy { field: CamAssetSortField! direction: SortDirection! } enum CamAssetSortField { NAME CREATED_AT UPDATED_AT ASSET_TYPE_ID } ``` ## GeoJSON Support Full GeoJSON geometry types supported: ```graphql theme={null} union GeoJSONGeometry = | GeoJSONPoint | GeoJSONLineString | GeoJSONPolygon | GeoJSONMultiPoint | GeoJSONMultiLineString | GeoJSONMultiPolygon | GeoJSONGeometryCollection ``` ### Example Geometries **Point:** ```json theme={null} { "type": "Point", "coordinates": [-114.0719, 51.0447] } ``` **Polygon:** ```json theme={null} { "type": "Polygon", "coordinates": [[ [-114.073, 51.045], [-114.071, 51.045], [-114.071, 51.044], [-114.073, 51.044], [-114.073, 51.045] ]] } ``` ## Audit Information All assets include audit metadata: ```graphql theme={null} type AuditInfo { createdAt: DateTime! createdBy: UserReference updatedAt: DateTime updatedBy: UserReference version: Int } ``` ## Error Handling Mutations return standardized error types: ```graphql theme={null} type AssetMutationResult { asset: CamAsset correlationId: ID errors: [AssetMutationError!] } type AssetMutationError implements MutationError { message: String! type: String! } ``` Common error types: * `DUPLICATE_ID`: Asset ID already exists * `INVALID_PARENT`: Parent asset not found or invalid type * `INVALID_PROPERTY`: Property validation failed * `INVALID_GEOMETRY`: GeoJSON geometry is malformed * `MISSING_REQUIRED`: Required field not provided * `INVALID_ASSET_TYPE`: Asset type does not exist ## Extension System Assets can integrate with external data sources through extensions: ```graphql theme={null} type AssetTypeExtension { id: ID! name: String! sourceType: ExtensionSourceType! connectionDetails: AssetTypeExtensionConnectionDetails stateSyncProperties: [AssetTypeExtensionStateSyncProperty!] statusProperties: [AssetTypeExtensionStatusProperty!] } enum ExtensionSourceType { DATABASE API FILE STREAM } ``` ## Batch Operations ### Upload Flow 1. Generate presigned S3 upload URL 2. Upload CSV/JSONL file to S3 3. Trigger batch upsert with reference 4. Monitor processing status ### File Formats **CSV:** ```csv theme={null} id,name,assetTypeId,properties.operator,geometry.coordinates site-001,Station A,site,ACME Energy,"[-114.0719,51.0447]" ``` **JSONL:** ```jsonl theme={null} {"id":"site-001","name":"Station A","assetTypeId":"site","properties":{"operator":"ACME Energy"},"geometry":{"type":"Point","coordinates":[-114.0719,51.0447]}} ``` ## Related Resources * **[CAM Assets Guide](../guides/cam-assets)** - Comprehensive usage guide * **[Common Patterns](../common-patterns)** - Pagination and filtering * **[Full SDL Schema](../schemas/sdl/su-cam-assets.graphql)** - Complete type definitions * **[Core Platform Guide](../guides/core-platform)** - Maps and geospatial services # Catalog Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/catalog Technical reference for the su-catalog subgraph providing data catalog and metadata services. # Catalog Subgraph Reference The `su-catalog` subgraph provides data catalog and metadata management. ## Subgraph Information * **Name**: `su-catalog` * **Routing URL**: `https://mhwrba73jc.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2023-10-13 * **SDL**: [View Schema](../schemas/sdl/su-catalog.graphql) ## Overview Dataset catalog, observed properties, and metadata management. ## Root Query Fields ```graphql theme={null} extend type Query { catalogs(withInternal: Boolean): Catalogs catalogDatasets(withInternal: Boolean): UpSpecifications pipeCatalogs: Catalogs @deprecated } ``` ## Root Mutation Fields ```graphql theme={null} extend type Mutation { provisionCatalogDataset( input: ProvisionCatalogDatasetInput! mutationId: ID! correlationId: ID ): UpSpecificationMutationResult } ``` ## Related Resources * **[Full SDL Schema](../schemas/sdl/su-catalog.graphql)** - Complete type definitions # Detections Ingress Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/detections-ingress Technical reference for the su-detections-ingress subgraph handling detection data ingestion. # Detections Ingress Subgraph Reference The `su-detections-ingress` subgraph handles incoming detection data ingestion. ## Subgraph Information * **Name**: `su-detections-ingress` * **Routing URL**: `https://rur9cuj7p0.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2025-10-09 * **SDL**: [View Schema](../schemas/sdl/su-detections-ingress.graphql) ## Overview Detection dataset ingestion and registration. ## Root Query Fields ```graphql theme={null} extend type Query { detectionsIngressDatasets(group: ID): [CamEngineDataset!]! } ``` ## Root Mutation Fields ```graphql theme={null} extend type Mutation { reloadDetectionsIngressDatasets(group: ID): [CamEngineDataset!]! } ``` ## Related Resources * **[Emissions Guide](../guides/emissions)** - Detection workflows * **[Full SDL Schema](../schemas/sdl/su-detections-ingress.graphql)** - Complete type definitions # Event Hub Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/eventhub Technical reference for the su-eventhub subgraph providing event publishing and subscriptions. # Event Hub Subgraph Reference The `su-eventhub` subgraph provides event publishing and subscription capabilities. ## Subgraph Information * **Name**: `su-eventhub` * **Routing URL**: `https://c5913dk85i.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2025-08-01 * **SDL**: [View Schema](../schemas/sdl/su-eventhub.graphql) ## Overview Event-driven integration and notifications. ## Root Query Fields ```graphql theme={null} extend type Query { eventHubPublishedEvents: EventHubPublishedEvents } ``` ## Related Resources * **[Overview](../overview)** - GraphQL API introduction * **[Full SDL Schema](../schemas/sdl/su-eventhub.graphql)** - Complete type definitions # Forms Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/forms Technical reference for the su-forms subgraph providing dynamic XForms data collection. # Forms Subgraph Reference The `su-forms` subgraph provides dynamic form definitions and data collection using ODK XForms. ## Subgraph Information * **Name**: `su-forms` * **Routing URL**: `https://9gfflct3kf.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2023-10-13 * **SDL**: [View Schema](../schemas/sdl/su-forms.graphql) ## Overview XForms-based data collection, form templates, and responses. ## Root Query Fields ```graphql theme={null} extend type Query { formLists: FormLists } ``` ## Root Mutation Fields ```graphql theme={null} extend type Mutation { createFormList(input: CreateFormListInput!, mutationId: ID, correlationId: ID): FormListMutationResult updateFormList(input: UpdateFormListInput!, mutationId: ID, correlationId: ID): FormListMutationResult } ``` ## Related Resources * **[Full SDL Schema](../schemas/sdl/su-forms.graphql)** - Complete type definitions # Issues Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/issues Technical reference for the su-issues subgraph providing issue tracking and task management. # Issues Subgraph Reference The `su-issues` subgraph provides comprehensive issue tracking, task management, and data collection capabilities. ## Subgraph Information * **Name**: `su-issues` * **Routing URL**: `https://6vapx1z4c0.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2025-11-03 * **SDL**: [View Schema](../schemas/sdl/su-issues.graphql) ## Overview This subgraph owns: * Issue creation and management * Task and multi-task coordination * Issue templates * Data collection forms (XForms integration) * Annotations and comments * Issue-asset relationships ## Root Query Fields ```graphql theme={null} extend type Query { # Issue Management issues: Issues allIssues(after: String, first: Int, status: IssueStatus, severity: Int, subjectReference: ID, triggerReference: ID): IssuesConnection openIssueBySubjectAndReference(subjectReference: ID!, triggerReference: ID!): Issue # Issue Types issueMultitask: IssueMultitask issueTask: IssueTask issueSeverityTypes: [IssueSeverityDisplay!] # Forms & Datasets issueDataCollectionFormReferences: [IssueDataCollectionForm!] @deprecated formDatasets(group: ID!): [CamEngineDataset!]! issuesDatasets(group: ID!): [CamEngineDataset]! } ``` ## Root Mutation Fields ```graphql theme={null} extend type Mutation { # Issue Lifecycle triggerIssue(input: TriggerIssueInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! updateIssue(input: UpdateIssueInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! deleteIssue(input: DeleteIssueInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! undeleteIssue(input: UndeleteIssueInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! transitionIssueState(input: TransitionIssueStateInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! closeIssue(input: CloseIssueInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! @deprecated reopenIssue(input: ReopenIssueInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! @deprecated # Multitask & Subtasks triggerIssueMultitask(input: TriggerIssueMultitaskInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! triggerIssueSubTask(input: TriggerIssueSubTaskInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! createMultitaskProcedure(input: CreateMultitaskProcedureInput!): IssueMultitaskProcedureMutationResult! triggerIssueTask(input: TriggerIssueTaskInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! # Assignment & Comments assignIssueToUser(input: AssignIssueToUserInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! acknowledgeAssignment(input: AcknowledgeAssignment!, delayed: DelayedIssueMutationInput): IssueMutationResult! commentIssue(input: CommentIssueInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! deleteIssueComment(input: DeleteIssueCommentInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! modifyIssueComment(input: ModifyIssueCommentInput!, delayed: DelayedIssueMutationInput): IssueMutationResult! # State & Data updateIssueStateData(input: UpdateIssueStateDataInput, delayed: DelayedIssueMutationInput): IssueMutationResult! bulkUpdateIssues(input: BulkUpdateIssuesInput!, delayed: DelayedIssueMutationInput): BulkIssuesMutationResult! # Data Collection Forms createIssueTaskDataCollectionForm(input: CreateIssueTaskDataCollectionFormInput!): IssueTaskDataCollectionFormMutationResult! updateIssueTaskDataCollectionForm(input: UpdateIssueTaskDataCollectionFormInput!): IssueTaskDataCollectionFormMutationResult! deleteIssueTaskDataCollectionForm(input: DeleteIssueTaskDataCollectionFormInput!): IssueTaskDataCollectionFormMutationResult! activateIssueTaskDataCollectionForm(id: ID!, subjectAssetProfile: ID): IssueTaskDataCollectionFormMutationResult! deactivateIssueTaskDataCollectionForm(id: ID!): IssueTaskDataCollectionFormMutationResult! cloneIssueTaskDataCollectionForm(input: CloneIssueTaskDataCollectionFormInput!): IssueTaskDataCollectionFormMutationResult! # Datasets reloadFormDatasets(group: ID): [CamEngineDataset!]! generateFormResponseDataset(async: Boolean! = true, formReference: String!): FormResponseCamDatasetGenerateResults! generateFormResponseDatasets(async: Boolean! = true): FormResponseCamDatasetGenerateResults! } ``` ## Core Types ### Issue Main issue/task type. ```graphql theme={null} type Issue implements Node @key(fields: "id") { id: ID! type: IssueType! # ISSUE, TASK, MULTITASK, SUBTASK taskType: IssueTaskType title: String! description: String status: IssueStatus! # OPEN, IN_PROGRESS, RESOLVED, CLOSED severity: Int! openedAt: DateTime! closedAt: DateTime dueAt: DateTime pastDue: Boolean subject: IssueSubject! trigger: IssueTrigger! annotations: [Annotation] assignee: IssueAssignee watchers: [IssueWatcher!] currentState: IssueState! auditHistory: [IssueAuditEntry!]! parentIssue: IssueReference } ``` ### IssueTemplate Reusable issue definition. ```graphql theme={null} type IssueTemplate @key(fields: "id") { id: ID! title: String! description: String type: IssueType! defaultSeverity: Int defaultDueInDays: Int formReference: XFormReference } ``` ## XForms Integration Issues can include data collection forms: ```graphql theme={null} type XFormDetails { model: XFormXMLNode! binds: [XFormBind!] body: [XFormBodyNode!] } type XFormBind { nodeset: String! type: XFormDataType! # string, int, decimal, date, geopoint, etc. required: XFormXPath constraint: XFormXPath } ``` ## Entity Extensions ### Asset Extends Asset with issue subject information. ```graphql theme={null} type Asset @key(fields: "profile id") @extends { profile: ID! @external id: ID! @external issueSubject: IssueSubject! } ``` ## Related Resources * **[Full SDL Schema](../schemas/sdl/su-issues.graphql)** - Complete type definitions # Maps Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/maps Technical reference for the su-maps subgraph providing mapping and visualization services. # Maps Subgraph Reference The `su-maps` subgraph provides mapping, visualization, and geospatial services. ## Subgraph Information * **Name**: `su-maps` * **Routing URL**: `https://jeoej0m171.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2025-02-07 * **SDL**: [View Schema](../schemas/sdl/su-maps.graphql) ## Overview Map configurations, layers, and geospatial visualization. ## Root Query Fields ```graphql theme={null} extend type Query { maps: Maps mapsConfig: MapsConfig } ``` ## Root Mutation Fields ```graphql theme={null} extend type Mutation { createMap(input: CreateMapInput!): MapMutationResult! cloneMap(id: ID!): MapMutationResult! updateMap(input: UpdateMapInput!): MapMutationResult! recordMapViewed(id: ID!): MapMutationResult! deleteMap(id: ID!): MapMutationResult! } ``` ## Related Resources * **[Full SDL Schema](../schemas/sdl/su-maps.graphql)** - Complete type definitions # Methane LDAR Backend Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/methane-ldar-backend Technical reference for the su-methane-ldar-backend subgraph providing LDAR operations and emission tracking. # Methane LDAR Backend Subgraph Reference The `su-methane-ldar-backend` subgraph provides comprehensive Leak Detection and Repair (LDAR) operations, emission observation tracking, and inspection workflow management. ## Subgraph Information * **Name**: `su-methane-ldar-backend` * **Routing URL**: `https://x2ex1v41i5.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2025-09-25 * **SDL**: [View Schema](../schemas/sdl/su-methane-ldar-backend.graphql) ## Overview This subgraph owns: * Emission observations (detections) * Inspection requests (OGI, drone) * Equipment and component clues * Detection resolution workflows * Emission observation reports * Compliance severity tracking ## Root Query Fields ```graphql theme={null} extend type Query { emissionObservations: EmissionObservations emissionObservationReports: EmissionObservationReports inspectionRequests: InspectionRequests noDetections: NoDetections emissionEvents: EmissionEvents methaneLdarBackendDatasets(group: ID!): [CamEngineDataset!]! methaneLdarBackendConfig: EmissionConfig methaneLdarBackendConfigs(group: ID!): EmissionConfigs genAi: GenAi } ``` ## Root Mutation Fields ```graphql theme={null} extend type Mutation { # Emission Observation Operations createEmissionObservation(input: CreateEmissionObservationInput!): EmissionObservationMutationResult! deleteEmissionObservation(input: DeleteEmissionObservationInput!): EmissionObservationMutationResult! acknowledgeEmissionObservation(input: AcknowledgeEmissionObservationInput!): EmissionObservationMutationResult! attributeEmissionObservationToEquipment(input: AttributeEmissionObservationToEquipmentInput!): AttributeEmissionObservationToEquipmentResult! attributeEmissionObservationToSite(input: AttributeEmissionObservationToSiteInput!): AttributeEmissionObservationToSiteResult! attributeEmissionObservationsToEquipment(input: AttributeEmissionObservationsToEquipmentInput!): AttributeEmissionObservationsToEquipmentResult! # Detection Operations createDetection(input: CreateDetectionInput!): DetectionMutationResult! updateDetection(input: UpdateDetectionInput!): DetectionMutationResult! updateHistoricalDetection(input: UpdateHistoricalDetectionInput!): DetectionMutationResult! resolveDetection(input: ResolveDetectionInput!): DetectionMutationResult! pendDetection(input: PendDetectionInput!): DetectionMutationResult! # Venting Event Operations createVentingEvent(input: CreateVentingEventInput!): VentingEventMutationResult! updateVentingEvent(input: UpdateVentingEventInput!): UpdateVentingEventResult! # Inspection Request Operations createInspectionRequest(input: CreateInspectionRequestInput!): InspectionRequestMutationResult! updateInspectionRequest(input: UpdateInspectionRequestInput!): InspectionRequestMutationResult! updateInspectionRequestStatus(input: UpdateInspectionRequestStatusInput!): InspectionRequestMutationResult! # Clue Operations updateClue(input: UpdateClueInput!): ClueMutationResult! # No Detection Operations createNoDetection(input: CreateNoDetectionInput!): NoDetectionMutationResult! updateNoDetection(input: UpdateNoDetectionInput!): NoDetectionMutationResult! deleteNoDetection(input: DeleteNoDetectionInput!): NoDetectionMutationResult! # Emission Event Operations createEmissionEvent(input: CreateEmissionEventInput!): EmissionEventMutationResult! updateEmissionEventFalseAlarmStatus(input: UpdateEmissionEventFalseAlarmStatusInput!): EmissionEventMutationResult! @deprecated updateEmissionEventStatus(input: UpdateEmissionEventStatusInput!): EmissionEventMutationResult! attributeEmissionEvent(input: EmissionEventAttributionInput!): EmissionEventMutationResult! correlateEmissionEvents(input: EmissionEventsCorrelationInput!): EmissionEventsCorrelationResult! unCorrelateEmissionEvents(input: EmissionEventsUncorrelationInput!): EmissionEventsUncorrelationResult! deleteEmissionEvents(input: DeleteEmissionEventsInput!): EmissionEventMutationResult! # Alarm Operations createAlarm(input: CreateEmissionAlarmInput!): EmissionAlarmMutationResult! updateAlarm(input: UpdateEmissionAlarmInput!): EmissionAlarmMutationResult! # Dataset & Configuration Operations reloadMethaneLdarBackendDatasets(group: ID!): [CamEngineDataset!]! generateNoDetectionsDatasets(input: NoDetectionsDatasetsInput!): NoDetectionsDatasetsResult! setMethaneLdarConfig(group: ID!, id: ID!, value: JSONObject!): EmissionConfigMutationResult manageEmissions(dryRun: Boolean): ManageEmissionsMutation } ``` ## Core Types ### EmissionObservation Detected emission event requiring investigation. ```graphql theme={null} type EmissionObservation @key(fields: "id") { id: ID! displayName: String! priority: EmissionObservationPriority! # HIGH(100), MEDIUM(50), LOW(1) status: DetectionStatus! detectionType: DetectionType! # SATELLITE, FLYOVER, DRONE, OGI, etc. phenomenonTime: DateTime! receivedAt: DateTime! geometry: GeoJSONGeometryInterface clues: [ClueReference!] inspectionRequests: [InspectionRequestReference!] resolutionMode: ResolutionMode audit: EmissionObservationAudit! } ``` ### Detection Types ```graphql theme={null} enum DetectionType { DETECTION_TYPE_SATELLITE DETECTION_TYPE_FLYOVER DETECTION_TYPE_DRONE DETECTION_TYPE_OGI # Optical Gas Imaging DETECTION_TYPE_CMS # Continuous Monitoring System DETECTION_TYPE_OWD # On-site Walk Down DETECTION_TYPE_VENTING_FLARING_BLOWDOWN DETECTION_TYPE_MANUAL } ``` ### Detection Status ```graphql theme={null} enum DetectionStatus { DETECTION_STATUS_NEW DETECTION_STATUS_VISUAL_INSPECTION_SCHEDULED DETECTION_STATUS_VISUAL_INSPECTION_COMPLETED DETECTION_STATUS_OGI_REQUESTED DETECTION_STATUS_OGI_SCHEDULED DETECTION_STATUS_OGI_COMPLETED DETECTION_STATUS_LEAK_REPAIR_SCHEDULED DETECTION_STATUS_LEAK_REPAIRED DETECTION_STATUS_VERIFICATION_SCHEDULED DETECTION_STATUS_RESOLVED } ``` ### InspectionRequest Request for follow-up inspection. ```graphql theme={null} type InspectionRequest { id: ID! detectionReference: DetectionReference! inspectionType: InspectionType! # INSPECTION_OGI, INSPECTION_DRONE status: InspectionStatus! additionalComment: String clues: [ClueReference!] requestedBy: InspectionRequestRequester audit: InspectionRequestAudit! siteId: ID multitaskProcedureId: String } ``` ### Equipment & Clues Equipment context for detections: ```graphql theme={null} type Equipment { id: ID! name: String! description: String siteReference: SiteReference! components: [EquipmentComponent!] } type Clue { clueId: ID! displayName: String! equipment: Equipment } ``` ## Resolution Modes ```graphql theme={null} enum ResolutionMode { DETECTION_RESOLVED_CORRELATED # Correlated with another detection DETECTION_RESOLVED_FALSE_ALARM # False positive DETECTION_RESOLVED_READY_TO_RECONCILE # Ready for compliance reporting } ``` ## Entity Extensions ### Site Extends Site with emission observation reports. ```graphql theme={null} type SiteReference @key(fields: "siteId") { siteId: ID! emissionObservationReports: EmissionObservationMonthSiteReportConnection } ``` ## Related Resources * **[Emissions Guide](../guides/emissions)** - LDAR workflows and examples * **[Full SDL Schema](../schemas/sdl/su-methane-ldar-backend.graphql)** - Complete type definitions # Methane Reconcile Backend Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/methane-reconcile-backend Technical reference for the su-methane-reconcile-backend subgraph providing emissions reconciliation. # Methane Reconcile Backend Subgraph Reference The `su-methane-reconcile-backend` subgraph provides emissions reconciliation and compliance reporting. ## Subgraph Information * **Name**: `su-methane-reconcile-backend` * **Routing URL**: `https://8fzyria1t5.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2025-08-15 * **SDL**: [View Schema](../schemas/sdl/su-methane-reconcile-backend.graphql) ## Overview Emissions reconciliation, compliance status, and reporting. ## Root Query Fields ```graphql theme={null} extend type Query { reconciledEmissions: ReconciledEmissions reconciledReports: ReconciledReports reconciledDecisions: ReconciledDecisions reconciliationErrors: ReconciliationErrors co2eSiteMonthReports: Co2eSiteMonthReports co2eMonthReports: Co2eMonthReports scope2Emissions: Scope2Emissions reconciliationSiteMonths: ReconciliationSiteMonths reconciliationMonths: ReconciliationMonths reconciliationReports: ReconciliationReports } ``` ## Root Mutation Fields ```graphql theme={null} extend type Mutation { updateReconciledEmission(input: UpdateReconciledEmissionInput!): ReconciledEmissionMutationResult! logReconciliationError(input: LogReconciliationErrorInput!): ReconciliationErrorMutationResult! logReconciliationDecision(input: LogReconciliationDecisionInput!): ReconciliationDecisionMutationResult! confirmReconciliationDecision(input: ConfirmReconciliationDecisionInput!): ReconciliationDecisionMutationResult! requestDecisionsReviewForApproval(input: RequestDecisionsReviewForApprovalInput!): ReconciliationDecisionMutationResult! approveDecisionsReviewRequest(input: ApproveDecisionsReviewRequestInput!): ReconciliationDecisionMutationResult! reopenReconciliationSiteMonth(input: ReopenReconciliationSiteMonthInput!): ReconciliationSiteMonthMutationResult! exportReconciledEmissions(input: ExportReconciledEmissionsInput!): ExportReconciledEmissionsMutationResult! updateScope2Emission(input: UpdateScope2EmissionInput!): Scope2EmissionMutationResult! triggerReconciliation(input: TriggerReconciliationInput!): TriggerReconciliationMutationResult! reconcileEmissionEvents(input: ReconcileEmissionEventsInput!): ReconcileEmissionEventsMutationResult! upsertRolledUpReconciledEmissions(input: UpsertRolledUpReconciledEmissionsInput!): RolledUpReconciledEmissionsMutationResult! } ``` ## Related Resources * **[Emissions Guide](../guides/emissions)** - Reconciliation workflows * **[Full SDL Schema](../schemas/sdl/su-methane-reconcile-backend.graphql)** - Complete type definitions # Sites Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/sites Technical reference for the su-sites subgraph providing site management. # Sites Subgraph Reference **Deprecated**: The `su-sites` subgraph is deprecated and will be removed in a future release. For geospatial operations and site management, use the **[Maps API](../subgraphs/maps)** (`su-maps`) instead. For connected asset management including asset hierarchy and locations, use the **[CAM Assets API](../subgraphs/cam-assets)** (`su-cam-assets`). The `su-sites` subgraph provides site management and hierarchy capabilities. ## Subgraph Information * **Name**: `su-sites` * **Routing URL**: `https://2af2daotz8.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2024-07-22 * **SDL**: [View Schema](../schemas/sdl/su-sites.graphql) ## Overview Physical sites, hierarchies, boundaries, and geospatial operations. ## Related Resources * **[Maps Subgraph Reference](./maps)** - Modern geospatial API (recommended) * **[CAM Assets Guide](../guides/cam-assets)** - Asset hierarchy and locations * **[Core Platform Guide](../guides/core-platform)** - Maps and geospatial services * **[Full SDL Schema](../schemas/sdl/su-sites.graphql)** - Complete type definitions # User Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/user Technical reference for the su-user subgraph providing user management. # User Subgraph Reference The `su-user` subgraph provides user profile and management capabilities. ## Subgraph Information * **Name**: `su-user` * **Routing URL**: `https://a4g6fd62uk.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2025-06-23 * **SDL**: [View Schema](../schemas/sdl/su-user.graphql) ## Overview User profiles, permissions, and account management. ## Root Query Fields ```graphql theme={null} extend type Query { userGroups: [UserGroup!] userConsentDocuments: [ConsentDocument!] me: User users: [User!] issueUserAssignees: [User!] } ``` ## Root Mutation Fields ```graphql theme={null} extend type Mutation { updateGroup(input: UpdateGroupInput!): UpdateGroupMutationResult! updateUserMeConsent(input: UpdateUserMeConsentInput!): UpdateUserMeConsentMutationResult! createUser(input: CreateUserInput!): UserMutationResult! updateUser(input: UpdateUserInput!): UserMutationResult! updateUserPreference(input: UpdateUserPreferenceInput!): UserMutationResult! updateUserRegisterNotificationToken(input: UpdateUserNotificationTokenInput!): UserMutationResult! updateUserUnregisterNotificationToken(input: UpdateUserNotificationTokenInput!): UserMutationResult! deleteUser(input: DeleteUserInput!): UserMutationResult! loginMe: UserMutationResult! } ``` ## Related Resources * **[Authentication Guide](../authentication)** - User authentication * **[Full SDL Schema](../schemas/sdl/su-user.graphql)** - Complete type definitions # Workflow Subgraph Reference Source: https://docs.sensorup.com/api/graphql/subgraphs/workflow Technical reference for the su-workflow subgraph providing workflow state machines. # Workflow Subgraph Reference The `su-workflow` subgraph provides workflow definitions and state machine management. ## Subgraph Information * **Name**: `su-workflow` * **Routing URL**: `https://mx2birfjx1.execute-api.us-west-2.amazonaws.com/poc/graphql` * **Last Updated**: 2023-10-13 * **SDL**: [View Schema](../schemas/sdl/su-workflow.graphql) ## Overview Workflow state machines, transitions, and orchestration. ## Root Query Fields ```graphql theme={null} extend type Query { workflows(withInternal: Boolean): Workflows } ``` ## Root Mutation Fields ```graphql theme={null} extend type Mutation { createWorkflow(input: CreateWorkflowInput!): WorkflowMutationResult! cloneWorkflow(id: ID!): WorkflowMutationResult! updateWorkflow(input: UpdateWorkflowInput!): WorkflowMutationResult! deleteWorkflow(id: ID!): WorkflowMutationResult! transferWorkflow(id: ID!, group: String!, username: String!): WorkflowMutationResult! activateWorkflow(id: ID!): WorkflowMutationResult! deactivateWorkflow(id: ID!): WorkflowMutationResult! } ``` ## Related Resources * **[Full SDL Schema](../schemas/sdl/su-workflow.graphql)** - Complete type definitions # MCP Usage Examples Source: https://docs.sensorup.com/api/mcp/examples Practical examples of using SensorUp MCP tools with AI assistants ## Overview This guide provides practical examples of how to use SensorUp MCP tools with AI assistants. These examples demonstrate common use cases and best practices. ## Basic Queries ### Listing Assets **Prompt:** ``` Using the SensorUp MCP tool, show me all my assets ``` **What Happens:** The AI assistant will use the Asset Tool to query your assets and present them in a readable format. **Expected Response:** * List of asset names and IDs * Asset status information * Basic metadata *** ### Getting Emission Events **Prompt:** ``` Show me emission events from the last 7 days using SensorUp MCP ``` **What Happens:** The AI assistant will use the Event Tool with appropriate date filters to retrieve recent emission events. **Expected Response:** * List of emission events * Event dates and times * Event status and details *** ## Advanced Queries ### Analyzing Trends **Prompt:** ``` Using SensorUp MCP, analyze emission trends for the last 30 days and identify any patterns ``` **What Happens:** The AI assistant will: 1. Use the Analytics Tool to retrieve emission data 2. Process the data to identify trends 3. Present insights in a clear format **Expected Response:** * Trend analysis * Pattern identification * Data visualization suggestions *** ### Asset Status Monitoring **Prompt:** ``` Check the status of all my assets and alert me to any that are inactive ``` **What Happens:** The AI assistant will: 1. Query all assets using the Asset Tool 2. Filter by status 3. Highlight inactive assets **Expected Response:** * Summary of asset statuses * List of inactive assets * Suggested actions *** ## Complex Workflows ### Event Investigation **Prompt:** ``` Using SensorUp MCP, find the emission event with the highest rate from last month and show me its details including associated assets ``` **What Happens:** The AI assistant will: 1. Query emission events from last month 2. Identify the event with the highest rate 3. Retrieve detailed event information 4. Query associated asset data 5. Present a comprehensive report **Expected Response:** * Event details * Emission rate information * Associated asset information * Timeline data *** ### Custom Reporting **Prompt:** ``` Create a summary report of my emission operations for the last quarter using SensorUp MCP ``` **What Happens:** The AI assistant will: 1. Query emission events for the quarter 2. Retrieve relevant analytics 3. Aggregate the data 4. Format it as a report **Expected Response:** * Summary statistics * Key metrics * Trend analysis * Comparative data *** ## Integration Patterns ### Daily Monitoring **Use Case:** Set up daily emission monitoring **Prompt:** ``` Check my SensorUp data for any new emission events today and summarize them ``` **Benefits:** * Quick daily updates * Early issue detection * Consistent monitoring *** ### Asset Health Checks **Use Case:** Regular asset status reviews **Prompt:** ``` Review the health status of all my assets and identify any that need attention ``` **Benefits:** * Proactive maintenance * Status visibility * Operational insights *** ## Best Practices ### 1. Be Specific with Time Ranges Good: "Show me events from the last 7 days" Better: "Show me emission events from January 1-7, 2025" ### 2. Request Relevant Fields Good: "Get asset data" Better: "Get asset names, IDs, and current status" ### 3. Use Follow-up Questions Start broad, then drill down: 1. "Show me all emission events" 2. "Show me details for event #12345" 3. "What assets are associated with that event?" ### 4. Combine Multiple Queries Ask for related data in one prompt: "Show me emission events from last week and the associated asset status for each event" ## Troubleshooting ### No Data Returned **Issue:** Query returns empty results **Solutions:** * Verify date ranges are correct * Check filter parameters * Confirm you have data for the requested period ### Permission Errors **Issue:** Tool reports insufficient permissions **Solutions:** * Verify your API key permissions * Check user role assignments * Contact your administrator ### Rate Limit Reached **Issue:** Tool reports rate limit exceeded **Solutions:** * Wait before making additional requests * Reduce query frequency * Optimize query patterns ## Related Resources * [Getting Started](/api/mcp/getting-started) * [Available Tools](/api/mcp/tools) * [GraphQL Query Patterns](/api/graphql/common-patterns) * [API Authentication](/api/graphql/authentication) # Getting Started with MCP Source: https://docs.sensorup.com/api/mcp/getting-started Learn how to set up and configure SensorUp MCP tools for your AI assistant ## Prerequisites Before you begin, ensure you have: * A SensorUp account with appropriate permissions * An API key for authentication (see [Authentication](/api/graphql/authentication)) * An MCP-compatible AI assistant or application (e.g., Claude Desktop, Cline, etc.) ## Installation ### Using npx (Recommended) The SensorUp MCP server can be installed and run using npx: ```bash theme={null} npx @sensorup/mcp-server ``` ### Using npm Alternatively, install globally: ```bash theme={null} npm install -g @sensorup/mcp-server ``` ## Configuration ### MCP Server Configuration Configure your MCP client to connect to the SensorUp MCP server. The configuration will vary depending on your MCP client. #### Example: Claude Desktop Configuration Add the following to your Claude Desktop configuration file: ```json theme={null} { "mcpServers": { "sensorup": { "command": "npx", "args": ["@sensorup/mcp-server"], "env": { "SENSORUP_API_KEY": "your-api-key-here", "SENSORUP_API_URL": "https://api.sensorup.com/graphql" } } } } ``` ### Environment Variables The SensorUp MCP server requires the following environment variables: * `SENSORUP_API_KEY`: Your SensorUp API key * `SENSORUP_API_URL`: The SensorUp GraphQL API endpoint (defaults to production) ## Verification Once configured, verify the connection by asking your AI assistant to: 1. List available MCP tools 2. Query basic information from your SensorUp account ## Next Steps * Explore [Available MCP Tools](/api/mcp/tools) * Review [Usage Examples](/api/mcp/examples) * Learn about [SensorUp GraphQL API](/api/graphql/overview) ## Troubleshooting ### Connection Issues If you're experiencing connection issues: 1. Verify your API key is valid 2. Check that your API endpoint URL is correct 3. Ensure your network allows outbound HTTPS connections 4. Review the MCP server logs for error messages ### Authentication Errors If you encounter authentication errors: 1. Confirm your API key has the necessary permissions 2. Check if your API key has expired 3. See [Authentication](/api/graphql/authentication) for more details ## Support For additional help, please contact SensorUp support or refer to the [MCP Official Documentation](https://modelcontextprotocol.io). # MCP Overview Source: https://docs.sensorup.com/api/mcp/overview Introduction to the Model Context Protocol (MCP) integration with SensorUp ## What is MCP? The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). MCP enables seamless integration between LLM applications and external data sources and tools. ## SensorUp MCP Integration SensorUp provides MCP tools that allow AI assistants to interact with your SensorUp data and operations directly. Through MCP, you can: * Query your asset data * Access emission event information * Retrieve operational insights * Interact with the SensorUp GraphQL API ## Benefits * **Seamless AI Integration**: Connect AI assistants directly to your SensorUp data * **Standardized Protocol**: Uses the open MCP standard for broad compatibility * **Secure Access**: MCP tools use your existing SensorUp authentication * **Real-time Data**: Access live data from your SensorUp account ## Getting Started To begin using SensorUp MCP tools, see the [Getting Started](/api/mcp/getting-started) guide. ## Learn More * [Available MCP Tools](/api/mcp/tools) * [Usage Examples](/api/mcp/examples) * [MCP Official Documentation](https://modelcontextprotocol.io) # Available MCP Tools Source: https://docs.sensorup.com/api/mcp/tools Reference guide for SensorUp MCP tools and their capabilities ## Overview SensorUp provides a set of MCP tools that enable AI assistants to interact with your SensorUp data and operations. Each tool is designed to perform specific tasks using the SensorUp GraphQL API. ## Core Tools ### Query Tool Execute GraphQL queries against the SensorUp API. **Capabilities:** * Read asset data * Query emission events * Retrieve operational metrics * Access user and organization information **Input Parameters:** * `query`: GraphQL query string * `variables`: Optional query variables **Example Usage:** Ask your AI assistant: "Query my assets using the SensorUp MCP tool" *** ### Asset Tool Retrieve and manage asset information. **Capabilities:** * List assets * Get asset details * Query asset status * Access asset metadata **Input Parameters:** * `assetId`: Optional asset identifier * `filters`: Optional filters for asset queries **Example Usage:** Ask your AI assistant: "Show me all my active assets" *** ### Event Tool Access emission event data and analytics. **Capabilities:** * List emission events * Get event details * Query event statistics * Access event timeline data **Input Parameters:** * `eventId`: Optional event identifier * `dateRange`: Optional date range filter * `status`: Optional event status filter **Example Usage:** Ask your AI assistant: "Show me emission events from the last 30 days" *** ## Data Tools ### Analytics Tool Retrieve analytical insights and metrics. **Capabilities:** * Get summary statistics * Query trend data * Access dashboard metrics * Generate custom reports **Input Parameters:** * `metricType`: Type of metric to query * `dateRange`: Date range for analytics * `groupBy`: Optional grouping parameter **Example Usage:** Ask your AI assistant: "Get emission trends for the last quarter" *** ## Tool Permissions All MCP tools respect your SensorUp user permissions. Tools can only access data and perform operations that your API key is authorized for. ## Rate Limits MCP tools are subject to the same rate limits as the SensorUp GraphQL API. See [Performance](/api/graphql/performance) for details. ## Tool Development SensorUp MCP tools are built on the Model Context Protocol standard. For information about creating custom tools or extending existing ones, refer to the [MCP Official Documentation](https://modelcontextprotocol.io). ## Best Practices 1. **Be Specific**: Provide clear, specific requests to your AI assistant 2. **Use Filters**: Leverage filtering parameters to reduce response sizes 3. **Check Permissions**: Ensure your API key has appropriate permissions 4. **Monitor Usage**: Keep track of your API usage and rate limits ## Related Resources * [Getting Started](/api/mcp/getting-started) * [Usage Examples](/api/mcp/examples) * [GraphQL API Reference](/api/graphql/overview) * [Authentication](/api/graphql/authentication) # Introduction to Connected Assets Source: https://docs.sensorup.com/overview/intro-connected-assets Discover SensorUp's Connected Assets: Unify, standardize, and visualize emissions data from diverse sources. Build a connected asset registry, apply custom business logic, and integrate seamlessly for proactive emissions management. # Introduction to Connected Assets SensorUp's **Connected Assets** module is the foundation of your emissions management strategy, empowering you to harness the power of unified data for smarter asset management. It provides a comprehensive platform to seamlessly integrate data from diverse sources, customize business logic, visualize critical information, and establish a connected asset registry, ensuring precise analysis and informed decision-making across your entire asset portfolio. > [!NOTE] > > Connected Assets ensures all your emissions-related data—from sensors, remote monitoring, or periodic inspections—is harmonized, enabling precise comparisons, comprehensive trend analysis, and a proactive approach to emissions management. ## The Challenge: Siloed & Underutilized Asset Data Organizations often struggle with asset and emissions data that is: * **Fragmented:** Data resides in multiple, disconnected systems (SCADA, sensor platforms, inspection tools, spreadsheets). * **Inconsistent:** Different data formats and lack of standardization hinder effective analysis and comparison. * **Delayed:** Field data often lags behind operational needs, causing delays in decision-making. * **Difficult to Contextualize:** Relating disparate data points back to specific assets or operational events can be challenging. ## How Connected Assets Solves This SensorUp Connected Assets provides a unified solution to: * **Integrate Multi-Source Data:** Bring together data from a wide variety of measurement sources and existing systems. * **Standardize Information:** Harmonize data into a consistent format for accurate comparisons and trend analysis. * **Build a Connected Asset Registry:** Establish a digital twin of your physical assets, including their properties and relationships. * **Enable Advanced Visualization:** Utilize powerful map and time-series views to interpret, correlate, and act on emissions data. * **Customize Business Logic:** Define rules and workflows for managing alerts, events, and data processing. * **Facilitate No-Code Integrations:** Easily connect with other systems in your tech stack for data ingress and egress. ## Core Capabilities of Connected Assets Connected Assets offers a suite of robust features to transform your raw data into actionable intelligence: > [accordion] Unified Data Integration & Standardization > > Seamlessly bring together and harmonize data from all your relevant sources. > > * **Multi-Source Data Ingestion:** Connect to various measurement sources including sensors, SCADA systems, OGI reports, flyovers, and manual inspection data. > * **Data Harmonization Engine:** Automatically standardizes diverse data formats and units into a consistent structure, enabling accurate comparisons and comprehensive trend analysis. > * **Real-time Data Synchronization:** Ensures that field data is aligned with central operations, minimizing delays in decision-making (where source systems support it). > [accordion] Connected Asset Registry > > Build and maintain a comprehensive digital representation of your physical assets. > > * **Flexible Asset Modeling:** Define and manage various asset types such as facilities, sites, wells, pipelines, platforms, and individual equipment components. > * **Asset Hierarchy & Relationships:** Establish parent-child and other relationships between assets to accurately model your operational structure and enable contextual analysis. > * **Customizable Asset Attributes:** Define and track specific properties and metadata for each asset type relevant to your operations and reporting needs. > [accordion] Advanced Visualization & Analytics > > Interpret, correlate, and act on emissions data through powerful visual tools. > > * **Interactive Map Views:** Visualize asset locations, sensor readings, and emission events geographically to understand spatial relationships and identify hotspots. > * **Time Series Analysis:** Plot data over time to identify trends, anomalies, and patterns in emissions or operational parameters. > * **Correlated Data Views:** Overlay different datastreams (e.g., emissions and operational data) to understand relationships and potential causal factors. > [accordion] Customizable Business Logic & Alerting > > Define and automate responses to specific conditions and events. > > * **Rule-Based Event Handling:** Configure specific rules and workflows for managing alerts and events, ensuring timely responses aligned with operational goals. > * **Automated Notifications:** Set up alerts to notify relevant personnel when predefined thresholds are breached or specific conditions are met. > * **Workflow Triggering:** Initiate automated workflows or actions based on incoming data or defined business logic. > [accordion] No-Code & Low-Code Integrations > > Easily connect Connected Assets with your broader technology ecosystem. > > * **Intuitive Data Ingress:** Configure connections to bring data into Connected Assets from various sources without requiring custom coding. > * **Flexible Data Egress:** Share standardized and processed asset and emissions data with other enterprise systems (e.g., ERP, Field Service Management, ESG platforms) using no-code interfaces. ## Conceptual Workflow for Leveraging Connected Assets The following steps outline a general process for utilizing Connected Assets to manage your emissions data: ### 1. 1. Define & Build Your Asset Registry Identify all relevant physical assets. Use the **Connected Asset Registry** tools to create their digital representations, define types, attributes, and hierarchies within SensorUp. ### 2. 2. Integrate Data Sources Connect your various data sources (sensors, SCADA, inspection tools, etc.) using **Multi-Source Data Ingestion** capabilities, including no-code connectors where applicable. Data is then standardized by the **Data Harmonization Engine**. ### 3. 3. Configure Business Logic & Alerts Define rules for how incoming data should be processed. Set up **Customizable Business Logic** for alerts, event triggers, and notifications based on thresholds or specific data patterns. ### 4. 4. Visualize & Analyze Data Utilize **Advanced Visualization Tools** (map views, time series charts) to monitor asset performance, analyze emission trends, and correlate different datastreams for deeper insights. ### 5. 5. Act on Insights & Share Data Based on analysis and alerts, initiate operational responses or further investigations. Use **No-Code Integrations** to share enriched and contextualized data with other enterprise systems for broader operational use or reporting. ## Key Benefits of Using Connected Assets * **Single Source of Truth:** Consolidate all asset-related emissions data into one harmonized platform. * **Enhanced Data Accuracy & Consistency:** Standardization eliminates discrepancies from diverse data formats. * **Improved Decision-Making:** Real-time data (where available) and advanced visualizations provide actionable insights. * **Increased Operational Efficiency:** Automated alerts and streamlined data access reduce manual effort. * **Greater Value from Existing Tech:** Seamlessly integrates with and enhances your current technology investments. * **Proactive Emissions Management:** Enables early detection of anomalies and trends for timely intervention. > [!TIP] > > With Connected Assets, you gain unparalleled control and visibility over your emissions data, transforming it from a complex challenge into a strategic asset. ## Next Steps To maximize your use of Connected Assets: > [card] [Getting Started with Assets](/use-sensorup/assets/getting-started) > > Learn how to set up and manage your asset registry and hierarchies. > [card] [Asset Technical Specifications](/use-sensorup/assets/assets-model) > > Detailed documentation on the asset data model and technical specifications. # Introduction to Connected Markets Source: https://docs.sensorup.com/overview/intro-connected-markets Discover SensorUp's Connected Markets: Streamline emissions data management, ensure regulatory compliance (GHGRP, OGMP 2.0), simplify market participation (Veritas), and perform robust emissions accounting. # Introduction to Connected Markets SensorUp's **Connected Markets** module is your central hub for driving compliance and achieving success in both regulatory and voluntary emissions markets. It integrates cutting-edge data management and reporting capabilities to streamline adherence to stringent frameworks like GHGRP and OGMP 2.0, simplify your participation in environmental initiatives such as Veritas, and ensure your emissions accounting is accurate and audit-ready. > [!NOTE] > > Connected Markets empowers your technical teams to proactively manage compliance, mitigate risks, and enhance transparency across all reporting activities by centralizing and reconciling emissions data. ## The Challenge: Navigating Complex Market & Regulatory Demands Organizations face significant hurdles in managing emissions data for compliance and market participation: * **Diverse Reporting Requirements:** Meeting the specific needs of multiple regulatory bodies (e.g., GHGRP) and voluntary programs (e.g., OGMP 2.0, Veritas) is complex. * **Data Aggregation & Validation:** Consolidating data from various systems and ensuring its accuracy is time-consuming. * **Reconciliation & Discrepancies:** Aligning bottom-up (source-level) and top-down (site-level) inventories requires sophisticated tools. * **Maintaining Auditability:** Ensuring all data, calculations, and adjustments are traceable is paramount. ## How Connected Markets Solves This SensorUp Connected Markets provides a unified solution to: * **Centralize Reporting Data:** Act as the nexus for all market-related data inputs. * **Streamline Compliance Workflows:** Configure and manage processes according to specific regulatory and voluntary program needs. * **Facilitate Market Participation:** Provide real-time insights and ensure data meets standards for initiatives like OGMP 2.0 and Veritas. * **Enable Robust Data Reconciliation:** Integrate various data sources to calculate and reconcile bottom-up and top-down inventories. * **Support Effective Accounting Processes:** Implement collaborative workflows for emissions data management. ## Core Capabilities of Connected Markets Connected Markets offers a suite of powerful features to manage your emissions reporting and market interactions: > [accordion] Centralized Reporting Hub > > Serves as the primary platform for all emissions data related to market participation and regulatory reporting. > > * **Multi-Source Data Aggregation:** Ingests and consolidates data from emissions monitoring devices, SCADA, manual inputs, third-party sources, and other enterprise systems. > * Standardized data intake normalizes diverse formats. > * A validation engine checks data quality and adherence to standards. > * **Unified Emissions Inventory:** Creates a comprehensive view of emissions across all assets and sources, including historical data management. > [accordion] Compliance & Market Program Management > > Tools and workflows to manage and streamline adherence to various reporting requirements. > > * **OGMP 2.0 Reconciliation & Reporting:** > * Facilitates yearly reconciliation of site-level and source-level inventories. > * Highlights discrepancies and incorporates associated uncertainties for each inventory type. > * Analyzes contributions from different source categories (stationary combustion, tank venting, fugitives). > * Aims for congruence between bottom-up and top-down estimates when accounting for uncertainty. > * Integrates site-level measurements (CMS, drones, flyovers) directly into the workflow to improve data quality and attribute emissions. > * **Veritas-Compatible Reconciliation:** > * Supports monthly emissions reconciliation aligned with Veritas principles. > * Provides a dashboard showing total reconciled emissions, site statuses (open, in progress, closed), methane intensity, and production numbers. > * Allows drilldown into site-level, day-by-day reconciled emissions, identifying sources and applied rule sets (e.g., Veritas One rule set). > * Incorporates business processes like operator decisions, automated rule execution, error handling, and peer review submissions. > * **GHGRP Reporting Support:** Assists in preparing data and generating reports compliant with Greenhouse Gas Reporting Program requirements. > * **Customizable Compliance Workflows:** Allows setup of reporting processes with task management, approvals, and comprehensive audit trail generation. > [accordion] Flexible Data Reconciliation & Accounting > > Advanced capabilities for integrating, reconciling, and accounting for emissions data. > > * **Bottom-up / Top-down Reconciliation Engine:** Enables the calculation and alignment of inventories derived from source-level estimates and site-level measurements. > * Includes tools for discrepancy analysis and uncertainty quantification. > * **SensorUp Carbon Calculator:** A low-code, configurable tool for arithmetic-based emissions calculations. > * **Observation Workflow:** Inspect incoming datastream records (e.g., CO2e per day) on a monthly basis, view charts, and apply common data correction approaches. > * **Data Snapshotting:** Fixes data for a specific reporting period to ensure calculation consistency. > * **Custom Calculation Builder:** Define formulas for metrics like methane intensity, CO2e, reconciliation adjustments, CDR credit generation, considering LCA boundaries and calculation nodes. > * **Effective Accounting Processes:** Supports collaborative workflows, peer review mechanisms, and streamlined month-end close for emissions data. ## Conceptual Workflow for Emissions Reconciliation & Reporting The following steps illustrate a general process within Connected Markets, adaptable for frameworks like OGMP 2.0 and Veritas: ### 1. 1. Data Aggregation & Inventory Setup Centralize all relevant data: bottom-up source-level estimates, top-down site-level measurements (flyovers, CMS, satellite), and operational data like production figures. ### 2. 2. Framework-Specific Reconciliation * **For OGMP 2.0 (Yearly):** Compare site-level and source-level inventories. Analyze discrepancies and uncertainties. Drill into source categories and incorporate site-level measurements to refine data and aim for congruence between inventories when uncertainty is accounted for. * **For Veritas (Monthly):** Review reconciled emissions dashboard. Drill into sites for day-by-day breakdowns. Apply Veritas rule sets and manage operator decisions for reconciliation. ### 3. 3. Data Correction & Calculation (Carbon Calculator) Inspect detailed datastream records (e.g., daily CO2e). Apply data corrections. Create a "snapshot" to fix data for the reporting period. Run configured calculations for methane intensity, CO2e, etc. ### 4. 4. Review, Approvals & Finalization Utilize built-in business processes for internal review, peer approval, and finalization of reconciled data and calculations. ### 5. 5. Report Generation & Export Generate reports formatted for specific regulatory bodies (GHGRP, OGMP 2.0) or voluntary programs (Veritas). Export data for submissions or to monitoring dashboards. ## Key Benefits of Using Connected Markets * **Streamlined Compliance:** Simplify adherence to complex frameworks like OGMP 2.0, GHGRP, and Veritas. * **Improved Accuracy:** Rigorous reconciliation processes and uncertainty management lead to more reliable emissions figures. * **Actionable Insights:** Understand discrepancies between inventory types and pinpoint areas for data quality improvement. * **Enhanced Auditability:** Maintain a clear record of data inputs, calculations, decisions, and rule applications. * **Flexible Calculations:** The Carbon Calculator allows for tailored accounting methodologies. > [!TIP] > > SensorUp Connected Markets utilizes all available data types to prioritize and produce the most accurate estimates for robust emissions reconciliation and reporting. ## Next Steps To delve deeper into the capabilities of Connected Markets: > [card] [Solutions for Simplifying OGMP](/solutions/enterprise-solutions/solutions-for-simplifying-ogmp) > > Learn how SensorUp simplifies OGMP 2.0 reporting and reconciliation. > [card] [Integrated Emission Management](/solutions/enterprise-solutions/integrated-emission-management-solution) > > Explore our comprehensive solution for emissions management and reporting. # Introduction to Connected Operations Source: https://docs.sensorup.com/overview/intro-connected-operations Learn how SensorUp's Connected Operations seamlessly integrates emission management with field service actions, streamlining workflows from detection to OGI inspection and repair verification using SensorUp Outpost. # Introduction to Connected Operations SensorUp's **Connected Operations** module bridges the critical gap between emission management and follow-up field service actions. It enables a seamless flow of information, allowing operators to review detections from various sources (flyovers, drones, CMS) within the emission management system and initiate actions like an OGI inspection, which then flows directly to field personnel using **SensorUp Outpost**, our mobile field application. > [!NOTE] > > Connected Operations enhances responsiveness, improves data accuracy, and ensures regulatory compliance by creating a cohesive, automated workflow from initial detection to field verification and repair. ## The Challenge: Disconnected Detection and Field Action Traditionally, acting on an emission detection often involves manual handoffs between office-based emission managers and field service teams: * Emission detected and analyzed in one system. * Separate communication (email, phone call) to request a field inspection. * Field data collected on paper or in a different mobile app. * Manual data entry back into the primary system. This disconnected process can lead to delays, data entry errors, and difficulty tracking the status of follow-up actions, ultimately impacting the speed of emission mitigation. ## How Connected Operations Solves This SensorUp Connected Operations streamlines this by: * **Integrated Action Initiation:** Directly create work orders (e.g., OGI inspection requests) from an emission event within the main platform. * **Seamless Data Flow to Mobile:** Work orders and relevant event details are automatically pushed to field operators via the SensorUp Outpost mobile app. * **Standardized Field Data Capture:** Field personnel use structured forms in Outpost to record findings, verify leaks, and document repairs, ensuring consistency (e.g., aligned with BCER, AER requirements). * **Real-time Synchronization:** Data captured in Outpost (including photos, annotations, and form submissions) syncs directly back to the emission event in the central platform. * **Automated Event Updates:** Actions in the field, like repairing a leak, can automatically update the emission event's status and end date. ## The Connected Operations Workflow: OGI Inspection Example Let's walk through a typical workflow where an emission detection triggers an OGI inspection request, managed through Connected Operations and SensorUp Outpost. **1. 1. Identify Need for Field Verification** Within the **Emission Ops** module, an air quality manager or operator reviews detections (from flyovers, drones, CMS, etc.). * If an emission event requires ground-level verification, the operator decides to initiate an OGI inspection. **2. 2. Create Work Item** From the emission event details page: * The operator clicks an "Action" button and select a work item like "OGI Inspection." * A dialog appears, often pre-populating relevant details from the emission observation (e.g., location, initial detection data). * **Notification (Optional):** The operator can enter email addresses in a "Send To" section to notify relevant stakeholders that an inspection has been requested. > [!NOTE] > > This action creates a new work item linked to the emission event. **3. 3. Track Work Item Progress** Back in the emission event details on the main platform, a "Work Item" section appears. * This section allows office personnel to track the progress of the OGI inspection (e.g., "Assigned," "In Progress," "Completed"). **4. 4. Field Operator Receives Task in SensorUp Outpost** The Work Item, along with associated emission event details, appears in the SensorUp Outpost mobile app for the assigned field technician. * The technician can review the task details and prepare for the site visit. **5. 5. On-Site Data Capture with Outpost** At the site, the field operator uses SensorUp Outpost: * **Site Check-in:** Completes any required site check-in forms. * **Record Leaks/Vents:** If a leak is found during the OGI survey, the operator uses the "+" button to record new leaks or verify existing ones. * **Standardized Forms:** Uses digital forms (e.g., designed to meet EPA, BCER or AER requirements) to document observations, leak details, component types, etc. * **Capture Visual Evidence:** Uses the camera feature within Outpost to take pictures or upload photos from their device. They can annotate these images directly in the app. **6. 6. Complete & Submit Inspection Survey** Once the Work Itemis complete and all findings are documented (e.g., leaks identified, components checked): * The operator completes the Work Item in Outpost. * All data, including forms, photos, and annotations, is submitted and synchronizes back to the central SensorUp platform. **7. 7. Review Field Data in Emission Event** Back in the main platform's emission event details: * The Work Item status updates to "Completed." * Office personnel can now review the newly collected data from the field, including detailed leak information, photos, and any findings from the inspection report. **8. 8. Emission Event Auto-Update & Closure** * **Automatic Updates:** If a leak is documented as repaired and verified in Outpost, this information syncs back. The emission event in the central platform can be configured to automatically update its end date based on the repair verification. This ensures accurate tracking of the event's duration. * **Event Closure:** Once the leak is confirmed repaired and all necessary documentation is complete, the operator can confidently close the emission event, completing the workflow and maintaining a full audit trail for compliance. ## Key Benefits of Connected Operations * **Improved Responsiveness:** Faster transition from detection to field action. * **Enhanced Data Accuracy:** Standardized digital forms and direct data sync reduce manual entry errors. * **Full Audit Trail:** Complete, end-to-end record of detection, inspection, findings, and resolution. * **Streamlined Compliance:** Easier to demonstrate due diligence and adherence to regulatory requirements (e.g., LDAR programs). * **Increased Efficiency:** Automated workflows reduce manual handoffs and administrative burden. * **Empowered Field Teams:** SensorUp Outpost provides field operators with the information and tools they need to perform their tasks effectively. > [!TIP] > > By connecting detections directly to field inspections through a simple, automated workflow, SensorUp Connected Operations significantly improves responsiveness, data accuracy, and regulatory compliance. ## Next Steps To learn more about leveraging Connected Operations and SensorUp Outpost: > [card] [Using SensorUp Outpost (Mobile App)](/use-sensorup/outpost-mobile/overview) > > A detailed guide for field operators on using the Outpost app for various inspection types and data capture. > [card] [Connected Operations OGI Workflow](/use-sensorup/connected-operations/connected-operations-ogi-workflow) > > Learn about the end-to-end workflow for OGI inspections and field operations. # Introduction to SensorUp Source: https://docs.sensorup.com/overview/intro-sensorup-platform Discover SensorUp, a configurable emissions management platform designed to integrate your data, streamline operations, ensure compliance, and accelerate your journey to significant emissions reduction. # Introduction to SensorUp: A Configurable Emissions Management Platform Welcome to SensorUp! We provide an enterprise-grade, **configurable emissions management platform** designed to help organizations like yours tackle the most pressing emissions challenges and **drive significant reduction at scale**. Our platform integrates your diverse data sources, streamlines complex workflows, and provides the actionable insights needed to achieve your sustainability and operational excellence goals. > [!NOTE] > > SensorUp empowers you to move beyond siloed data and manual processes, offering a unified, adaptable solution that accelerates your emissions reduction journey. ## The Challenge: Managing Emissions in a Complex Landscape Effectively managing and reducing emissions presents numerous hurdles: * **Data Overload & Silos:** Data from sensors, inspections, operational systems, and third-party feeds is often voluminous, disparate, and difficult to consolidate for a holistic view. * **Evolving Regulations & Market Demands:** Keeping pace with complex, changing compliance requirements (GHGRP, OGMP 2.0, Veritas) and voluntary market standards is a constant effort. * **Operationalizing Insights:** Translating raw data into actionable steps for field teams, operational adjustments, and strategic decisions can be slow and inefficient. * **Scaling Reduction Efforts:** Moving from pilot projects to enterprise-wide emissions reduction requires robust, scalable systems and processes. * **The "Build vs. Buy" Dilemma:** Developing a comprehensive, in-house emissions management solution is a massive undertaking, requiring significant time, specialized expertise, ongoing maintenance, and can divert focus from core business activities. ## The SensorUp Solution: Configuration & Integration at Scale SensorUp addresses these challenges by providing a **configurable platform**, not a rigid, one-size-fits-all product. We understand that each organization has unique assets, operational workflows, and reporting needs. Our approach combines the power of a specialized, off-the-shelf platform with the flexibility to adapt to your specific environment. **Key Pillars of Our Approach:** 1. **Unified Data Foundation (Connected Assets):** We start by helping you integrate and contextualize all your asset-related data, creating a single source of truth. (See [Introduction to Connected Assets](/overview/intro-connected-assets)) 2. **Streamlined Action & Workflow (Connected Operations):** We connect emission insights directly to field service actions and operational responses, automating and optimizing your workflows. (See [Introduction to Connected Operations](/overview/intro-connected-operations)) 3. **Assured Compliance & Market Readiness (Connected Markets):** We provide the tools for robust reconciliation, accurate reporting, and confident participation in regulatory and voluntary markets. (See [Introduction to Connected Markets](/overview/intro-connected-markets)) By integrating these pillars, SensorUp enables a continuous cycle of measurement, analysis, action, and reporting, all geared towards scalable emissions reduction. ## Why Choose a Configurable Platform like SensorUp? When considering how to tackle emissions management, the "build vs. buy" question is critical. Building a custom solution from scratch is resource-intensive and carries significant risk. SensorUp offers the advantages of a specialized platform while providing the configurability you need: > [accordion] Accelerate Time-to-Impact & Reduction > > Leverage a feature-rich platform built on years of emissions management expertise. Instead of spending 12-24+ months building a foundational system, you can start configuring SensorUp to your needs and seeing results much faster, accelerating your progress towards reduction targets. > [accordion] Focus on Your Core Mission, Not Software Development > > Your expertise lies in your core operations, not in building and maintaining complex enterprise software for emissions. SensorUp handles the underlying platform architecture, data models, security, scalability, and ongoing evolution, allowing your teams to focus on what they do best: reducing emissions and optimizing operations. > [accordion] Benefit from Deep Domain Expertise & Best Practices > > SensorUp is built with deep knowledge of emissions sources, regulatory frameworks (OGMP 2.0, GHGRP, Veritas), data standards (ISO 19156:2023), and industry best practices. This expertise is embedded in our platform, saving you the effort of acquiring and maintaining it internally. > [accordion] Achieve True Scalability & Future-Proofing > > Our platform is designed to scale with your needs, from managing a few assets to tens of thousands, and handling increasing data volumes from diverse sources. We continuously update SensorUp to incorporate new technologies, integrate with emerging data providers, and adapt to evolving regulatory landscapes, future-proofing your investment. > [accordion] Harness the Power of Configuration, Not Custom Code > > "Configurable" means you can tailor SensorUp to your specific asset hierarchies, data source schemas, business rules, workflows, and reporting formats primarily through setup and configuration UIs, low-code tools, and well-defined APIs—without extensive custom software development for every need. This provides flexibility while retaining the benefits of a standardized, supported platform. > [accordion] Comprehensive Integration Capabilities > > A major challenge in any emissions program is integrating data. SensorUp is designed for this, offering multiple pathways – from low-code connectors to direct data feeds (S3, SFTP) and managed integrations – to connect your existing systems and new data sources efficiently. (See [Getting Started with Integrations](/use-sensorup/user-management/getting-started-integrations)) ## Core Platform Modules at a Glance SensorUp's configurable power is delivered through its integrated modules: > [card] [Connected Assets](/overview/intro-connected-assets) > > Unify, standardize, and visualize all your asset and emissions data. Build a comprehensive asset registry as the foundation for accurate tracking and analysis. > [card] [Connected Operations](/overview/intro-connected-operations) > > Streamline workflows from methane detection to field verification and repair. Automate actions and connect office insights with field activities seamlessly. > [card] [Connected Markets](/overview/intro-connected-markets) > > Manage compliance with OGMP 2.0, GHGRP, Veritas, and other programs. Perform robust data reconciliation and generate accurate reports for all stakeholders. ## Who Benefits from SensorUp? Our platform is designed to support various roles within your organization: * **Operators & Field Teams:** Streamlined workflows, mobile tools, and clear actions. * **Air Quality, ESG & Environmental Managers:** Comprehensive data, robust reporting, and tools for compliance and reduction strategy. * **IT & Systems Integrators:** Flexible integration options, standardized data models, and a scalable architecture. * **Leadership & Strategy Teams:** Actionable insights for data-driven decisions and progress tracking towards sustainability goals. ## Navigating This Documentation These documents are designed to help you understand and effectively use the SensorUp platform: * **Introductions:** High-level overviews of SensorUp and its core modules. * **Getting Started Guides:** Practical steps for initial setup, data integration, and key workflows. * **Feature Guides:** In-depth explanations of specific functionalities within each module. * **API Reference:** Technical details for developers using our GraphQL API. We are excited to partner with you on your emissions reduction journey! # Welcome to SensorUp Documentation Source: https://docs.sensorup.com/overview/overview Explore SensorUp's emissions management platform. Find guides, feature explanations, and best practices for operators, air quality teams, and IT professionals. # Welcome to SensorUp Documentation SensorUp provides a comprehensive enterprise platform designed to tackle the most pressing emissions challenges in the oil and gas sector. These documents offer in-depth information on our solutions—Connected Assets, Connected Operations, and Connected Markets—to help you effectively manage emissions, ensure compliance, and achieve your sustainability goals. > [!NOTE] > > Our platform helps you stay connected to your assets, operations, and markets, transforming complex data into actionable insights for emission management excellence. ## Explore Our Platform Dive into the core components of the SensorUp Enterprise Platform. Each section provides detailed information on features, capabilities, and how to leverage them for optimal emissions management. > [card] [Introduction to SensorUp Platform](/overview/intro-sensorup-platform) > > Discover SensorUp's configurable emissions management platform designed to integrate your data, streamline operations, ensure compliance, and accelerate your journey to significant emissions reduction. > [card] [Introduction to Connected Assets](/overview/intro-connected-assets) > > Learn to unify, standardize, and visualize emissions data from diverse sources. Build a connected asset registry and apply custom business logic for proactive emissions management. > [card] [Introduction to Connected Operations](/overview/intro-connected-operations) > > Discover how to seamlessly integrate emission management with field service actions, streamlining workflows from detection to OGI inspection and repair verification. > [card] [Introduction to Connected Markets](/overview/intro-connected-markets) > > Understand how to streamline emissions data management, ensure regulatory compliance (GHGRP, OGMP 2.0), simplify market participation (Veritas), and perform robust emissions accounting. # Third-party data notices Source: https://docs.sensorup.com/overview/third-party-data-notices Third-party data used by SensorUp Studio and the licences it is provided under. This page lists third-party data used by SensorUp Studio and the licences it is provided under. ## Timezone boundaries Timezone lookup contains information from timezone-boundary-builder ([https://github.com/evansiroky/timezone-boundary-builder](https://github.com/evansiroky/timezone-boundary-builder)), which is made available under the Open Database License (ODbL) ([https://opendatacommons.org/licenses/odbl/1-0/](https://opendatacommons.org/licenses/odbl/1-0/)). Boundary data © OpenStreetMap contributors. # Oct, 7 2025 Source: https://docs.sensorup.com/releases/2025-10-07 This release includes the Asset Change Audit History and Permanent Asset Deletion features, offering enhanced control, transparency, and auditability over their asset data. Additionally, the mobile app experience was enhanced to streamline workflows for field operators and improve the app's stability. ## 🚀 New Features These new capabilities provide significant value and expanded functionality: * **Asset Change Audit History:** You can now view a complete history of changes to assets. This provides greater transparency and traceability for all modifications to your asset data. * **Permanent Asset Deletion for Super Admins:** A secure, two-step process has been implemented that allows Super Admins to permanently delete an asset after it has been archived. This ensures data retention policies can be met while preventing accidental deletion of active assets. * **Initiate Mobile Follow-Up Actions from Site Summary:** Users can now initiate follow-up actions directly from the site summary on Android devices. ## ✨ Minor Enhancements These improvements refine existing features and enhance your day-to-day workflow: * **Configurable Columns for Emission Observations:** You can now configure the columns on the Emission Observations page to show all schema fields. * **Improved Mobile Site Summary UI (iOS & Android):** * The tap target for the site summary has been enlarged on both iOS and Android, making it easier to navigate. * Category labels have been updated for clarity (e.g., "Outstanding leaks" is now "Leaking") and status naming has been unified ("Repaired + Verified" is now "Repaired"). * **Enhanced Asset Table Experience:** * A default column view is now available for the asset page, providing a consistent starting point before user customization. * The attribution modal now fetches asset children without causing the top-level attribution to disappear. * **Streamlined Mobile Login Experience (iOS):** * Users now have an improved experience for handling server input errors during login. * Users can easily navigate back from the username/password screen to the server selection view. * **Carbon Claim Details Update:** The "Claim URI" field has been added to the Claim Details section in the UI. * **Carbon Accounting Dashboard Screen Updates:** New carbon accounting dashboard metrics have been added, including total credits generated, capture, transport, and storage, along with new graphs. ## 🐞 Bug Fixes We've squashed several bugs to improve the stability and reliability: * **Corrected Data and Image Display:** * Fixed a bug where the top-level asset attribution would disappear after fetching child assets. * **UI and Navigation Fixes:** * Corrected the horizontal scroll behavior on the Heatmap and replaced the custom no-data component with the standard one. * Fixed a bug on Android tablets where rotating the screen on the site summary page would incorrectly redirect the user. * **Data Integrity and Performance:** * Fixed a bug where some newly imported CMS detections were being automatically closed without an end time defined. * Resolved an issue preventing the creation of an observation from the leak detail view before a Site Check-in was completed on iOS. ## ⚙️ Under the Hood Improvements These improvements enhance the performance, reliability, and scalability of the platform, laying groundwork for future advancements: * **AI Feature Foundation:** * Created the foundational infrastructure for upcoming AI micro-features, including a shared BaseAIService class, reusable React components, and shared GraphQL hooks. * **Mobile Architecture & Testing:** * Re-architected the Flutter module for the SensorHub iOS app to use a cleaner, faster, and more maintainable system. * Completed testing and configuration to ensure solutions work for mobile, including LaunchDarkly flags and backend compatibility. * **Database and Backend Logic:** * Developed a base data source class that wraps a Postgres table to streamline querying for reading and writing entities. * Optimized soft-delete performance by removing a backend check. # Nov, 21 2025 Source: https://docs.sensorup.com/releases/2025-11-21 This release focuses on LDAR + Emissions Ops Efficiency and Outpost Mobile Application improvements. Teams can now process multiple emission events simultaneously with new bulk actions, while mobile users benefit from enhanced form validation and improved app stability. We've also advanced our API integration capabilities and resolved critical bugs affecting data accuracy across both platforms. ## Web Application ### 🚀 Features * **Bulk Actions for Emission Events** - Process multiple emission events at once with new bulk capabilities for marking false alarms, closing events, and correlating detections. This streamlines workflows and reduces the time needed to manage large volumes of emission events. * **Edit Manually Created Emission Observations** - Update all fields of manually created emission observations after initial creation. All changes are tracked in the observation history, giving editors and admins full flexibility to refine data as needed. * **One-Click Coordinate Copying** - Quickly copy latitude and longitude coordinates from the emission events table and emission observation details blade with a single click, making it easier to share location data with field teams or integrate with other tools. * **Customizable View Options** - Toggle between map, timeline, and table views to focus on the information most relevant to your workflow. Hide or show different panels based on your current task. * **Simplified Asset Update Page** - Removed unnecessary fields from the asset update page to streamline the asset management workflow. * **Year Added to Issue Request Emails** - Issue request emails now include the year in the detection date to prevent confusion, especially for historical detections. ### 🐞 Bugs * **Fixed Asset Attribution Error** - Resolved an issue where follow-up requests were displaying the wrong asset. The system now correctly uses the emission event's asset reference to ensure accurate attribution. * **Fixed User Attribution in Observation History** - Corrected an issue where emission observation updates showed "system" instead of the actual user's name in the audit history. * **Resolved Emission Events Table Loading Error** - Fixed a critical error that prevented the emission events table from loading properly. * **Fixed Timeline Visualization Error** - Corrected an issue that caused timeline views to fail when loading state-based data. * **Fixed Map Layer Rendering Error** - Resolved a critical error that prevented map layers from rendering correctly. ## Mobile App ### 🚀 Features * **Auto-Scroll to Form Errors** - When submitting a form with errors or missing required fields, the app now automatically scrolls to the first error, helping users quickly identify and fix issues. * **Enhanced Download Progress Visibility** - Improved the resource download experience with detailed progress indicators showing both individual resource downloads and overall progress, preventing users from thinking the app has frozen. ### 🐞 Bugs * **Fixed Observation Timestamp Display (iOS)** - Added missing timestamps to observation cells for better data tracking and visibility. * **Improved Asset Search Zoom (iOS)** - Enhanced the zoom level when searching for assets on the main map, making it easier to locate specific assets in the field. # Dec 10, 2025 Source: https://docs.sensorup.com/releases/2025-12-10 This release includes various improvements and bug fixes across the platform. ## Web Application ### 🚀 Features * **Toggle Observations, Events** - Users can now easily switch between viewing individual observations and grouped emission events. This provides greater flexibility in analyzing emission data. ![Toggle between viewing observations and grouped emission events](https://mintcdn.com/sensorupinc/khzcKEBH-_ONOob4/images/group-by-event.gif?s=532e0a9c573512897f64c9525c77ceae) * **Enhanced Asset Event Table** - The Emission Events table now displays relevant asset properties for all attributed sources. This enhancement provides a more comprehensive view of your asset's emission data directly within the table. ![Asset properties displayed in the Emission Events table](https://mintcdn.com/sensorupinc/khzcKEBH-_ONOob4/images/asset-property-columns.gif?s=72e2935d60b24b50d2cd63ce06eefa7d) * **API Creates Follow-Up Tasks** - The Issues API can now create follow-up tasks when additional work is required. This allows external systems to seamlessly create actionable items within SensorUp. ### 🐞 Bugs * **Fixed Form Prefill** - We resolved an issue where forms were not correctly pre-filling from emission observations. This ensures accurate and efficient data entry. * **Filter Future Emission Events** - The time filter on the Emissions page now supports filtering for events with future dates. This provides greater flexibility in planning and forecasting emission activities. ## Mobile App ### 🚀 Features * **Mobile User Prefill** - Mobile forms now support pre-filling with the current user's information. This streamlines data entry and improves the mobile user experience. * **Improved Site Summary** - We have enhanced the Site Summary view for better clarity and usability. This update provides a more intuitive overview of site-specific data. ### 🐞 Bugs * **Fixed Submit Button Issue** - We fixed an issue where tapping the submit button during animation could lead to an invalid state. This ensures a smoother and more reliable submission process. # Jan 26, 2026 Source: https://docs.sensorup.com/releases/2026-01-21 This release includes various improvements and bug fixes across the platform. ## Web Application ### 🚀 Features * **View Event Short ID** - Users can now see the short ID for each Emission Event directly in the UI table. This makes it easier to quickly identify and reference specific events. ![View Event Short ID](https://mintcdn.com/sensorupinc/VnjqajTPfUKMbszo/images/release-notes/View%20Event%20Short%20ID.gif?s=74706fdda8fc97f59d140f8c0c74ea95) * **Delete Open Issues** - Users can now delete open issues and their associated sub-tasks. This provides greater control over managing and cleaning up your issue list. ![Delete Open Issues](https://mintcdn.com/sensorupinc/VnjqajTPfUKMbszo/images/release-notes/Delete%20Open%20Issues.gif?s=32adf7cf0a7a18911d8fdaf0733a0bec) * **Track External Observations** - We've added external IDs to observations. This enhancement improves data correlation and overall system stability for your observations. * **Remember Event Grouping** - The 'Group by Event' toggle now persists across user sessions. This ensures a consistent view of your data, saving you time and effort. * **Request Event Issues** - You can now request issues directly from Emission Events, with email notifications sent to relevant parties. This streamlines communication and follow-up for event-related issues. * **Add Issue Collaborators** - The issue creation modal now allows you to add collaborators. This facilitates teamwork and ensures everyone is informed about new issues. ![Add Issue Collaborators](https://mintcdn.com/sensorupinc/VnjqajTPfUKMbszo/images/release-notes/Add%20Issue%20Collaborators.gif?s=742876ecaecddcfc9205b10eb80c138b) * **Correct Volume Calculation** - Volume calculations now correctly return 0 when the duration is 0, instead of an undefined value. This ensures more accurate data reporting. * **Improved Issues Table** - The Issues table has been updated for improved performance and user experience. You'll notice a smoother and more responsive interface. * **View Site Summaries** - The 'Site Check' view has been replaced with a new 'Site Summary' roll-up view. This provides a more comprehensive overview of your site data. ![View Site Summaries](https://mintcdn.com/sensorupinc/VnjqajTPfUKMbszo/images/release-notes/View%20Site%20Summaries.gif?s=940fcdd360092d9351cff4454418f7f3) * **Filter Observations by Type** - You can now filter Emission Observations and Datasets by Detection Type. This allows you to see all relevant observations in a single, consolidated view. ![Filter Observations by Type](https://mintcdn.com/sensorupinc/VnjqajTPfUKMbszo/images/release-notes/Filter%20Observations%20by%20Type.gif?s=908971a4d647bb612b82039bffc99db4) * **Add Methane Density Option** - Users can now configure methane density settings directly from the User Preference Page. This enhancement provides greater control over emissions calculations and data accuracy. ![Add Methane Density Option](https://mintcdn.com/sensorupinc/VnjqajTPfUKMbszo/images/release-notes/Add%20Methane%20Density%20Option.gif?s=4c7739448751da15238ff4f0939d541c) ### 🐞 Bugs * **Group Follow-up Issues** - Follow-up issues are now automatically created with the correct group assignment. This ensures better organization and tracking of related issues. * **Fixed Observation Times** - The display of Emission Observation start and end times has been corrected. This ensures that timestamps accurately reflect the data without affecting other related information. * **Handle Deleted Issues** - Emission Events and Observations now correctly reflect the status of deleted issues and work items. This ensures data consistency across the platform. * **Transform Plume Images** - The platform now utilizes plume metadata from the data source to intelligently transform plume images on the map. This ensures more accurate and contextually relevant visualization of emission plumes. ## Mobile App ### 🚀 Features * **View Mobile Observations** - Mobile users can now view detailed Emission Observation information, including all associated data. This provides comprehensive insights on the go. * **Add Radio Buttons** - The Form Designer now includes radio buttons with conditional branching capabilities. This allows you to create more dynamic and intelligent forms. # Jan 29, 2026 Source: https://docs.sensorup.com/releases/2026-01-29 ## Asset Performance Improvements We migrated our operational asset data layer from DynamoDB to PostgreSQL. Asset interactions now load in under 1 second, reduced from 8+ seconds. ### Changes * **Assets page** — Asset inventory loads immediately. * **Asset hierarchy** — Parent-child relationships display instantly when selecting a site, well, or equipment. * **Emission event attribution** — Asset search and selection is now responsive during attribution workflows. * **Nearby assets** — Assets near an emission event load without delay. # Feb 11, 2026 Source: https://docs.sensorup.com/releases/2026-02-11 This release delivers emissions workflow improvements including plume layer controls, gas conversion preferences, and detection date visibility. Multiple bug fixes address data table reliability, email rendering, and inspection workflows across web and mobile platforms. ## Web Application ### 🚀 Features * **Toggle Plume Layers** - Users can now toggle plume layers on and off directly from the emissions map, making it easier to focus on specific emission sources without visual clutter.