UltimoSDK 1.4.0

Introduction

This is a package to help develop against the Ultimo API in C#.

Install

To use this package you need to install it with npm, or download the repo and add the code to your project.

Usage

To use this SDK, there are a few steps to follow

Create a client

To create a client all you need is an api key and a portal uri like so

// Do make sure to add the v1/object to this uri
UltimoClient client = new(new Uri("https://www.portalUri.com"), "apiKey");

Execute requests

Once a client has been created you can start to execute request, this will show an example of how to get a list of jobs with a filter

Get a list of jobs

UltimoListRequestData requestData = new()
{
    // This is one way to do it
    Filter = "Id eq \"0002\""

    // we could also use
    //Filters = new List<string>(){"Id eq \"0002\"", "Second filter"}
    // This uses a custom setter to set the Filter property
};

// Replace the Job with another BaseUltimoItem type and it should work
UltimoResponse<UltimoListResponse<Job>> response = client.GetUltimoListResponse<Job>(requestData, UriAddOn.Job);

Get a single item

UltimoResponse<Job> jobResponse = client.GetSingleItem("itemId", UriAddOn.Job)

Execute your own list request

UltimoListRequestData requestData = new()
{
    // This is one way to do it
    Filter = "Id eq \"0002\""

    // we could also use
    //Filters = new List<string>(){"Id eq \"0002\"", "Second filter"}
    // This uses a custom setter to set the Filter property
};
UltimoResponse<UltimoListResponse<Job>> response = client.Execute<UltimoListResponse<Job>>(requestData, "Job")
// Replace "Job" with endpoint add on e.g "ProcessFunction"
// Or use the UriAddOn enum instead

Read data or error from request

Once the response object has been obtained we can start to extract data from the response

Read data from UltimoResponse

if(response.Error != null || response.Result == null){
    Console.WriteLine($"Request failed because of empty result or with message {response.Error.Message}");
    return;
}

Job job = response.Result;
// Do something with the job

Read data from UltimoResponse<UltimoListResponse>

if(response.Error != null){
    Console.WriteLine($"Request to Ultimo failed with message: {response.Error.Message}");
    return;
}

foreach(JToken item in response.Result.Items){
    // Do something with item
}

(Optional) Create Request data or Response data

If you want the SDK to return a specific type of item you can create your own data model for the response or request data with some limitations

Create your own response type

To create your own response type, you can pass it along in the UltimoListResponse or create a class that implements UltimoResponse

Example 1, using UltimoListResponse

// Create model class
public class UltimoExampleResponse{
        // Make sure to use the JsonProperty attribute,
        [JsonProperty("jsonPropertyName")] // e.g "id"
        public string? Id { get; set; }

        // To ignore a property use the JsonIgnore attribute
        [JsonIgnore]
        public int example = 5
}
// Execute the request as normal except that the type is given along with the UltimoListResponse Type
UltimoResponse<UltimoListResponse<UltimoExampleResponse>> response = await client.ExecuteAsync<UltimoListResponse<UltimoExampleResponse>>(requestData, "Job");

// Now we can access the UltimoExample response item list again
// foreach(UltimoExampleResponse data in response.Items)
//{ Do something }

Example 2, creating a custom item response

// we use the UltimoExampleResponse class from the previous example
UltimoResponse<UltimoExampleResponse> response = client.Execute<UltimoExampleResponse>(requestData, UriAddOn.Job);

Example 3, Implementing BaseUltimoItem

The BaseUltimoItem class has a few properties found in most ultimo responses.
Such as but not limited to Context, GeocodeX and -Y and Id.

Creating a request using this can be done by simply implementing the class

public class Example : BaseUltimoItem
{
    [JsonAttribute("Example")]
    public string? Example { get; set; }
}

// Now we can use this class to convert responses into ultimo items
UltimoResponse<Example> response = client.GetSingleItem("itemId", "Custom endpoint")

Create request data

To create a different type of request data we implement the IUltimoRequestData interface This is just an empty interface, so the request can be any class that implements this empty interface.

// Create model class
public class UltimoExampleRequestData : IUltimoRequestData{
        // Make sure to use the JsonProperty attribute,
        [JsonProperty("jsonPropertyName")] // e.g "id"
        public string? Id { get; set; }

        // Make sure to use the JsonIgnore attribute on properties to ignore
        [JsonIgnore]
        public string? IgnoreMe { get; set; }
}

UltimoExampleRequestData requestData = new(){
    Id = "ExampleId"
};

// Execute request with new params
UltimoListResponse response = await client.ExecuteAsync<UltimoListResponse, UltimoExampleRequestData>(requestData, "Job");