HighGear.ApiClient 9.0.0.171

HighGear.ApiClient is the .NET client for the HighGear REST API.

Introduction

HighGear makes it easy to rapidly deploy and securely manage work, at scale. Empower everyday business users to start building seamless workflows and processes to get your entire team connected across the enterprise, with more visibility, auditability, and real-time measurement of all work activity. Assign tasks, manage work, track progress, and report the status of activity in real time using HighGear's no-code workflow and process management platform. Easily and securely.

And with HighGear's REST API, it's never been easier to rapidly integrate business applications and mission critical work, while HighGear's enterprise-grade security meets the rigors of the most highly regulated industries, keeping your data safe.

If you're interested in learning more about the HighGear platform, schedule a demo or contact us.

This package makes it easier to use the HighGear REST API from .NET applications, as it provides .NET methods and types (aka models) for calling into (and receiving data from) the REST API. It also includes other utilities for building integrations with the HighGear product.

Getting Started

To get started, install this package for your .NET application as follows. Make sure to specify the version of the HighGear API you want to use.

dotnet add package HighGear.ApiClient -v 9.0.0

Once you've done that, you will need to create an instance of the client. There are two ways of doing this:

// Create a client that uses an API key for authorization
HighGearApiClient client = HighGearApiClient.CreateForKey(
	host: "https://highgear.example.com",
	apiKey: "API KEY HERE"
);

// Create a client that uses a username and password for authorization via OAuth2
// Note: If the OAuth2 client is confidential, there is an optional clientSecret
// parameter where the client secret can be provided.
HighGearApiClient client = await HighGearApiClient.CreateUsingOAuthPasswordGrant(
	host: "https://highgear.example.com",
	username: "username",
	password: "password",
	clientId: "OAuth2 client_id"
);

Example: Getting Task Data

HighGearApiClient client = HighGearApiClient.CreateForKey("https://highgear.example.com", "API KEY HERE");

TaskGetModel<IReadOnlyDictionary<string, object>> task = await client.GetTask(3);

// Examples of getting field data
int taskId = task.JobId;
string briefDescription = (string)task.Fields["brief_description"];
ContactBasicInfo[] assignee = (ContactBasicInfo[])task.Fields["assignee"];

See the Field Value Types section below for a reference of what .NET value type is to be expected for each type of field.

Example: Verifying the Digital Signature of a Workflow Web Request

Each workflow web request contains a unique digital signature. The external system that receives the web request should verify the digital signature to be certain that the request originated from HighGear, to prevent unauthorized access.

(The below example verifies the digital signature using the public key obtained from an API connection. If you don't have an API connection, you can use another overload of DigitalSignatureHelper.VerifyDigitalSignature to provide the public key in PEM format loaded from a config file.)

// This is the MVC endpoint method. The WorkflowWebRequestContent type
// represents the web request body.
public async Task Post([FromBody] WorkflowWebRequestContent content)
{
    // Create the HighGearApiClient
    HighGearApiClient apiClient = HighGearApiClient.CreateForKey("https://highgear.example.com", "API KEY HERE");

    // Retrieve the digital signature from the header
    var signature = this.Request.Headers["X-HG-Workflow-Request-Signature"];

    // Verify the digital signature. This will throw an exception if the signature is not present or is invalid.
    await apiClient.VerifyDigitalSignature(content, signature);

    // Perform the work of your integration here
}

This example illustrates deserializing the WorkflowWebRequestContent model in a .NET Framework application. To do so, use the Newtonsoft.Json NuGet package.

.NET MVC applications can be configured to use Newtonsoft.Json for controllers using the AddNewtonsoftJson extension method in the Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet package:

var builder = WebApplication.CreateBuilder(args);
...
builder.Services.AddControllers().AddNewtonsoftJson();

Field Value Types

When getting task or contact data (which is returned from GetTaskAsync, GetContactAsync, the advanced search endpoints, and the task edit session endpoint), the .NET types for field values differ according to field type. The .NET types are as follows:

Additionally, there are three special fields of field type dropdown that have special .NET types: