Skip to main content
Version: Current

SDK usage and troubleshooting

Connections and authentication​

Create a ControlRoomContext, call Open(), and use its repository properties to make requests. Close the context when the application has finished using it. The reference examples focus on one operation; production code should manage the context's lifetime explicitly, as shown in Get started.

The SDK exposes access and refresh tokens. Treat both as secrets. Do not log tokens, passwords, or complete connection strings. The token model does not itself define a refresh policy: confirm renewal behavior in the SDK build deployed with your server, and handle authentication failures in the application. Avoid sharing a context concurrently unless your SDK's thread-safety contract permits it.

Use an account with the permissions required by the operation. Being able to log in does not imply permission to read every entity or perform administrative operations.

Asynchronous operations​

Use await for methods returning Task or Task<T>. A completed Task means that the SDK operation completed; the meaning of its result depends on the API. It does not universally mean that an automation job has finished executing.

public async Task ReadCurrentUserAsync(IControlRoomContext context)
{
    var user = await context.Users.GetCurrentUserAsync();
    Console.WriteLine(user);
}

Keep asynchronous calls asynchronous through the calling code. Blocking on .Result or .Wait() can block application threads and complicate exception handling.

Jobs: submit, execute, and monitor​

  • SubmitJobV2Async submits a job and returns job information. Do not interpret submission as successful completion of the automation.
  • ExecuteJobV2Async executes a process with the supplied arguments. Check the returned job information and status before consuming output; confirm completion and timeout behavior for your SDK build.
  • GetJobStatusAsync and GetJobInfoAsync let an application monitor a job using its ID.

Use input argument names and value types defined by the selected process. An empty dictionary is appropriate only when that process requires no input arguments. A nullable botId in a signature permits omission; it does not document which Buddy the server will select. Verify deployment assignment rules before relying on automatic selection.

When polling, use a bounded interval and an application-level deadline. Handle failed and suspended jobs as well as successful jobs. Do not assume a timed-out submission failed to create a job: check server state before resubmitting to avoid duplicate work.

Migrate from deprecated job methods​

Deprecated methodReplacementMigration check
SubmitJobAsyncSubmitJobV2AsyncThe V2 signature does not include waitForCompletion. Monitor the returned job ID when completion is required.
ExecuteJobAsyncExecuteJobV2AsyncThe V2 signature does not include timeOut. Review application deadlines and the installed SDK's execution behavior.

The V2 suffix identifies a method revision, not a .NET or server version. Confirm availability in the SDK assembly referenced by your project.

Pagination and task queries​

For APIs accepting skip and take, skip is the number of records to omit and take is the requested page size. Start with skip = 0 and a positive, bounded page size. Advance by the number of records returned. Stop on an empty page; use a documented total count when available. Server limits and concurrent changes can affect page contents.

For task APIs accepting TaskQueryOptions, configure paging, filters, sorting, and whether argument values are needed. Use a consistent sort when paging. The model page includes the filter and sort shapes used by the task examples.

The Tasks API provides named queries such as pending, overdue, department, and team tasks. Task Services covers configurable fetch queries and assignment/lifecycle operations. Both groups' examples use context.Tasks; the documentation groups describe their purpose rather than separate context properties.

Failures and troubleshooting​

Handle exceptions at the application boundary and record the operation, relevant entity IDs, and a sanitized error message. SDK-specific exception types and error codes must be checked against the installed assembly; these pages do not define a universal error-code contract.

SymptomWhat to check
Assembly or dependency cannot be loadedTarget framework, SDK version, referenced dependencies, and deployment output.
Connection cannot be openedBase URL, network access, TLS configuration, and server availability.
Login or authorization failsCredentials, enabled authentication mode, account status, and entity permissions.
Entity is absent or a query returns no resultsID/name, current environment, account visibility, and filter values.
A create or update request failsRequired fields, permitted values, process argument definitions, and account permissions.
A request times outServer/job state and whether the operation may already have taken effect.

Retry only failures your application has identified as transient, with a bounded retry policy. Before retrying a write, determine whether it already succeeded. Some bulk operations return individual successes and failures; inspect their response collections rather than treating a completed request as proof that every item succeeded.

Help improve this page