V2NodesServiceChannel
ServiceChannel
V2

ServiceChannel

ServiceChannel is a facilities and service-automation platform used to manage operational service data through the ServiceChannel v3 API surface.

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.1.2.1 - Preserved inherited fields in designer templates when OpenAPI schemas use constraints-only allOf overlays.
0.1.2.0 - Added supported paging continuation and sanitized request echoes for mutation responses.
0.1.0.0 - Completed the V2 overhaul with eager first-request startup and lazy input continuation.
0.0.0.12 - Aligned the V2 connector contract and public help article.
0.0.0.1 - Initial ServiceChannel V2 node article.
0.0.0.4 - Updated the article to match the current template-driven Create, Retrieve, Update, and Action methods.
0.0.0.5 - Updated the article to reflect the current access-token refresh behavior and supported runtime surface.
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 - Updated the article after the shared response-template fix so template outputs now reflect supported ServiceChannel provider payload shapes more reliably.
0.0.0.8 - Updated the article after the expired-token retry fix so the node refreshes once even when ServiceChannel returns its structured security-permissions authorization payload.
0.0.0.9 - Updated the article after the forced-refresh fix so expired cached tokens are reacquired correctly instead of reusing the stale persisted bearer token.
0.0.0.10 - Updated the article after the provider-error normalization fix so failed ServiceChannel calls no longer surface as successful OK responses.
0.0.0.11 - Updated the article after the OData response fix so top-level value collections emit one Flowgear row per item instead of one wrapper row.

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.

Property Type Description
Use Production Environment Boolean Uses the Production API and login endpoints instead of the Sandbox2 endpoints.
Client ID String OAuth client identifier issued by ServiceChannel during app registration.
Client Secret Masked OAuth client secret issued by ServiceChannel during app registration.
Username String Optional ServiceChannel username used when the connection must obtain a token through the password grant flow.
Password Masked Optional ServiceChannel password used when the connection must obtain a token through the password grant flow.
Access Token Masked Bearer token used for ServiceChannel API requests.
Refresh Token Masked OAuth refresh token used to renew the access token.
Timeout (seconds) Integer Timeout applied to token requests and connection validation calls.

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.
  • 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 path reacquires a fresh bearer token instead of reusing the stale persisted 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 current 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.

Parameter Type Description
Connection Connection ServiceChannel connection profile containing credentials and token state.
OperationId String Template-selected identifier for the ServiceChannel API operation to execute.
Options Object Optional path and query values for the selected operation.
Items Array Optional request body items sent to the selected ServiceChannel operation.
Return Type Description
Response Array Response items that include the provider payload fields together with Flowgear.IsSuccess, Flowgear.Message, and Flowgear.Request.

Retrieve

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

Parameter Type Description
Connection Connection ServiceChannel connection profile containing credentials and token state.
OperationId String Template-selected identifier for the ServiceChannel API operation to execute.
Options Object Optional path and query values for the selected operation.
Return Type Description
Response Array Response items that include the ServiceChannel business fields returned by the selected retrieve operation. Retrieve rows do not include mutation-style default fields.

Update

Use Update for supported PUT and PATCH operations that change ServiceChannel records.

Parameter Type Description
Connection Connection ServiceChannel connection profile containing credentials and token state.
OperationId String Template-selected identifier for the ServiceChannel API operation to execute.
Options Object Optional path and query values for the selected operation.
Items Array Optional request body items sent to the selected ServiceChannel operation.
Return Type Description
Response Array Response items that include the provider payload fields together with Flowgear.IsSuccess, Flowgear.Message, and Flowgear.Request.

Action

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

Parameter Type Description
Connection Connection ServiceChannel connection profile containing credentials and token state.
OperationId String Template-selected identifier for the ServiceChannel API operation to execute.
Options Object Optional path and query values for the selected operation.
Items Array Optional request body items sent to the selected ServiceChannel operation.
Return Type Description
Response Array Response items that include the provider payload fields together with Flowgear.IsSuccess, Flowgear.Message, and Flowgear.Request.

Usage Notes

  • Use the template picker in the Flowgear designer to browse the ServiceChannel operations available for each method.
  • Retrieve completes its provider request while the Node invoke is awaited.
  • Create, Update, and Action complete 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. If an endpoint supports paging, its paging inputs remain available in the template surface.
  • 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.
  • 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.
  • 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 use the current Items object, or Options for bodyless operations. Nested Content values are excluded.
  • 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 current node execution surface 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 expose through a customer-facing template contract.