ServiceChannel v2

Provides integration with ServiceChannel, a facilities and service-automation platform used to manage operational service data through the ServiceChannel v3 API.

The Flowgear ServiceChannel Node lets you call the supported ServiceChannel retrieve, create, update, and action operations by using built-in templates, OAuth-backed access, and normalized runtime responses in a Workflow.

Revision History

0.0.0.1 - Initial release.
0.0.0.4 - Introduced the template-driven Create, Retrieve, Update, and Action methods.
0.0.0.5 - Improved access-token refresh behavior.
0.0.0.6 - Removed work-order-specific template and paging behavior so the node follows the API-backed contract consistently.
0.0.0.7 - Improved response templates so they reflect supported ServiceChannel payload shapes more reliably.
0.0.0.8 - Refreshed expired tokens once even when ServiceChannel returns its structured security-permissions authorization payload.
0.0.0.9 - Reacquired expired cached tokens correctly instead of reusing the stale bearer token.
0.0.0.10 - Fixed failed ServiceChannel calls being reported as successful OK responses.
0.0.0.11 - Emitted one row per item for top-level OData value collections instead of one wrapper row.
0.0.0.12 - Aligned the connector contract.
0.1.0.0 - Completed the Runtime overhaul with eager first-request startup and lazy input continuation.
0.1.2.0 - Added supported paging continuation and sanitized request echoes for mutation responses.
0.1.2.1 - Preserved inherited fields in designer templates when OpenAPI schemas use constraints-only allOf overlays.
0.1.2.17 - Changed Update to accept a single Item and return a single Response object, added $top result limits, $skip offsets and CustomParameters placeholders to Retrieve templates, emitted one row per item for ServiceChannel count and page envelopes, and added automatic waits and retries when ServiceChannel rate limits a request.

Connection

Use the connection to choose the ServiceChannel environment and supply the OAuth credentials or token values that the node needs to call the API.

Setup Notes

• Register an application in ServiceChannel to obtain the required Client ID and Client Secret.
• ServiceChannel provides Sandbox2 and Production environments. The node defaults to Sandbox2 and can be switched to Production through the connection. Sandbox2 is a shared environment that ServiceChannel refreshes regularly.
• The connection supports either OAuth authorization-code sign-in or token acquisition using a ServiceChannel username and password when a refresh token is not available.
• When a cached access token has expired, the node refreshes it once before retrying the request when a refresh path is available on the connection, including the ServiceChannel authorization-failure case that can return a structured 504 security-permissions payload instead of a raw unauthorized exception.
• The forced refresh obtains a new bearer token instead of reusing the expired token that triggered the retry.
• Connection validation uses the general workorders read endpoint to confirm that the supplied token can reach the ServiceChannel API.

Methods

The node exposes template-driven Create, Retrieve, Update, and Action methods from the embedded ServiceChannel OpenAPI document. Only the operations that match the node's JSON execution and paging support are shown in the template picker.

Create

Use Create for supported POST operations that create ServiceChannel records or submit supported request bodies.

Retrieve

Use Retrieve for supported GET operations that read ServiceChannel records or reference data.

Update

Use Update for supported PUT and PATCH operations that change a ServiceChannel record. Update sends one request body and returns one response, so operations whose documented request or response is an array are not shown in the template picker.

Action

Use Action for supported business-action POST, PUT, or PATCH operations, such as template-driven ServiceChannel actions that are exposed separately from ordinary updates.

Usage Notes

• Use the template picker in the Flowgear designer to browse the ServiceChannel operations available for each method.
• Retrieve authenticates, validates the operation, and fetches the first page while the Node invoke is awaited. Later pages are fetched only as the Workflow consumes rows.
• Update sends its single Item and receives its response while the Node invoke is awaited.
• Create and Action send the first input item while the Node invoke is awaited. Later items are consumed lazily, and an empty connected input sends no provider request.
• The node embeds the Service Automation API document, so template discovery does not require a separate metadata call.
• Query and path parameters are exposed from the selected API operation.
• For Retrieve, $top limits the number of rows returned to the Workflow without changing the page size the node requests from ServiceChannel. Retrieve templates default $top to 10; remove the value to return all available rows.
• For Retrieve, $skip selects the starting offset. $count, page, and pageSize are not shown in templates because the node manages those paging values.
• Retrieve templates that include $filter or searchExpression also expose Options.CustomParameters. Declare each placeholder key with its @ prefix, for example @locationId, and reference it in the filter or search expression. Only exact, case-sensitive keys declared in CustomParameters are replaced, so other at-sign text such as an email address is sent unchanged. Values embedded in $filter are formatted as OData literals according to their type.
• Response templates are populated from the supported API success schema so the designer can show the current business row shape for Retrieve and the current mutation contract for Create, Update, and Action.
• When ServiceChannel returns a top-level OData-style object with a value array, the node emits one row per item in that array instead of returning the whole envelope as a single row.
• Top-level OData transport metadata such as @odata.context is not copied onto emitted rows, and retrieve templates expose the underlying item fields rather than the outer value wrapper.
• ServiceChannel count and page envelopes, such as Locations, Districts, Regions, Manufacturers, and Reviews, also emit one business item per row. Paging fields such as TotalCount, TotalElements, Page, and TotalPages are not emitted.
• If ServiceChannel responds to an expired token with its structured security-permissions payload, the node refreshes once and retries before returning the final provider response.
• If a second unauthorized response is returned after a token refresh, the node surfaces the provider failure instead of replacing it with a generic reconnect prompt.
• When ServiceChannel rejects a request because an application rate limit was exceeded, the node waits for the limit window reported by ServiceChannel, for example per [1] minute, and then retries. A request is retried at most twice. If ServiceChannel does not report a supported window, the rate-limit error is returned instead.
• Retrieve rows stay focused on ServiceChannel business data and do not add mutation-style default fields.
• If the first provider retrieve call fails, the Node surfaces that ServiceChannel error instead of converting it into an empty result.
• Create, Update, and Action rows use the Flowgear mutation defaults through the Flowgear object.
• Mutation request echoes in Flowgear.Request use the current Item or Items object, or Options for bodyless operations. Nested Content values are excluded.
• Successful 200 OK and 204 No Content mutation responses with empty bodies are returned as successful results.
• Provider payloads that include ServiceChannel error fields such as ErrorCode and ErrorMessage are normalized to Flowgear mutation failures instead of being reported as successful responses.

Known Issues

• Attachment endpoints are not shown in the template picker because the node is limited to JSON-based request and response handling.
• Some ServiceChannel API operations remain hidden when they require read-style POST behavior that the node does not yet support.