Skip to content

Essentials API Guide

Notes

This documentation describes the Application Programming Interfaces (API v2) for NorthStar Essentials version R2025 (formerly Create 14/Ruby) and later.

Introducing NorthStar Essentials API 2

Using this API, software programmers are able to produce documents in high volumes and manage customer communications, according to the different MHC Create layers.

The following features are matching the MHC Create solution:

  • Render documents dynamically, in real-time, using XML or JSON as input data to output formats such as PDF, HTML, Text.
  • Data Integration (SQL, XML, JSON, CSV, etc.).
  • Document Assembly Line (with additional inputs such as Word, Excel, PDF, TIFF, JPEG, SVG, Barcodes, Charts, 3-D Objects).
  • Use document templates created in MHC Studio to control layout, styles, colors and other visual aspects.

NorthStar Essentials provides the following APIs:

  • C# for .NET programmers by adding a reference to the Create.Client.NET.dll assembly
  • Java for Java programmers through the Create.Client.JAVA-2.0.0.jar package

The communication between these APIs and the MHC Create server is performed through REST endpoints via HTTP or HTTPS.

Notes

For NorthStar Essentials installations, the default ports are 50100 (HTTP) and 50101 (HTTPS). In the cloud however, only HTTPS (port 443) access is provided.

Live REST API Documentation

The REST API is accompanied by a live documentation page which allows you to send requests in real time and examine the response.

The Live REST API Inspector can be accessed via a web page under the /swagger URL. For a local installation using the default ports, this would be:

  • For HTTP: http://localhost:50100/swagger
  • For HTTPS: https://localhost:50101/swagger

The default ports can be updated in the webServerSettings.json configuration of the Web API service in C:\ProgramData\MHC Software folder, by setting the HttpConfig Port parameter, respectively HttpsConfig Port.

Getting Started

Authentication

NorthStar Essentials uses API keys in order to authenticate requests made by clients. You have to access the webServerSettings.json configuration of the Web API service in C:\ProgramData\MHC Software folder to find the API Key in order to use the Essentials API.

All endpoints require a session token. The token can be obtained using the Authorization service.

Template management

For core-only installations, templates are managed in the file system and can be found in the Management Console/Workspaces, under the default workspace. XML Document samples can be found in Start Menu under MHC Create Samples then access XML Samples. You can find here samples that prove the basic conversion capabilities: MHC Studio Publisher templates and XSL-FO files for XML to PDF conversion, and also DAL files use for document assembly.

Using .NET API

Using the .NET API is very easy and accessible for all users to retrieve and store files in the repository. The .NET assembly contains the client-side object model that needs to be downloaded by following the next section.

Downloading the API

For core-only installations, use the SDK download page, which by default is located at https://localhost:50101/sdk or http://localhost:50100/sdk.

If you are using the cloud version, these can be downloaded from the Developer\Software module, under the Programming tools and API's group section.

Using the API

For core-only installations, you need to make sure to use the correct server name and port number provided by your system administrator:

The code sample below uses the API to convert XML to PDF using a template stored on the NorthStar Essentials server. An XML string is sent to the server and a PDF is received back and downloaded locally.

string apiUrl = "https://api.example.com";
string apiKey = "898d6c1c-057f-4b8a-b429-c0bafa5a1ebf";
string downloadFolder = "C:/Temp/";
string fileName = "sample-xml2pdf.pdf";

try
{
    // Authenticate
    Configuration configuration = new Configuration() { BasePath = apiUrl };
    configuration.DefaultHeaders.Add("Authorization", "Basic " + Convert.ToBase64String(Encoding.UTF8.GetBytes(apiKey)));

    AuthorizationApi authorizationApi = new AuthorizationApi(configuration);
    string sessionToken = authorizationApi.GetToken().AccessToken;
    Configuration directRenderApiConfig = new Configuration()
    {
        BasePath = apiUrl,
        DefaultHeaders = new Dictionary<string, string>() { { "Authorization", "Basic " + Convert.ToBase64String(Encoding.UTF8.GetBytes(sessionToken)) } }
    };

    Console.WriteLine("Your token is: {0}", sessionToken);

    // Render XML -> PDF
    // Create a new Render API
    DirectRenderApi renderApi = new DirectRenderApi(directRenderApiConfig);

    var xml = "<?xml version=\"1.0\" standalone=\"yes\"?>" +
                "<root>" +
                    "<Invoices>" +
                        "<Invoice>" +
                            "<InvoiceProperties>" +
                                "<number>02116</number>" +
                                "<date>2016-06-10</date>" +
                            "</InvoiceProperties>" +
                            "<CustomerInformation>" +
                                "<name>Earl Library Co.</name>" +
                                "<address>1021 South Main Street,Seattle, Washington 92315</address>" +
                                "<email>sales@earlbook.com</email>" +
                                "<telephone>(206)321-2345</telephone>" +
                            "</CustomerInformation>" +
                            "<Products>" +
                                "<Product>" +
                                    "<id>1</id>" +
                                    "<name>Rendezvous with Rama by Arthur C. Clarke</name>" +
                                    "<price>15</price>" +
                                    "<quantity>3</quantity>" +
                                    "<total>45</total>" +
                                    "<description>An all-time science fiction classic, Rendezvous with Rama is also one of Clarke's best novels--it won the Campbell, Hugo, Jupiter, and Nebula Awards.</description>" +
                                "</Product>" +
                            "</Products>" +
                            "<Comments>" +
                                "<comments>Contact us with any questions you may have.</comments>" +
                            "</Comments>" +
                        "</Invoice>" +
                    "</Invoices>" +
                "</root>"

    // Create a new render request
    RenderRequestEntity request = new RenderRequestEntity()
    {
        InputSettings = new InputSettings()
        {
            Template = new Template()
            {
                Workspace = "Default",
                Path = @"Bookstore Invoice\Invoice.epr"
            }
        },
        Input = new Input()
        {
            InputFormat = "xml",
            Source = $"data:application/xml;base64,{Convert.ToBase64String(Encoding.UTF8.GetBytes(xml))}"            
        },
        PdfOutput = new PdfOutput()
    };

    // Send the request
    Stream response = renderApi.Render(request);

    Console.WriteLine("XML -> PDF rendered ok");

    // Download the PDF locally
    if (!Directory.Exists(downloadFolder))
        Directory.CreateDirectory(downloadFolder);

    // Write the file
    using (System.IO.Stream newFile = System.IO.File.OpenWrite(downloadFolder + fileName))
    {
        response.CopyTo(newFile);
    }

    Console.WriteLine("Downloaded response file to folder: {0}", downloadFolder + fileName);
}
catch (Exception ex)
{
    Console.WriteLine("Error: {0}", ex.Message);
}

Using Java API

The Java API will need the same client-side object model mentioned above written in Java.

Downloading the API

For core-only installations, use the SDK download page, which is by default located at https://localhost:50101/sdk or http://localhost:50100/sdk.

If you are using the cloud version, these can be downloaded from the Developer\Software module, under the Programming tools and API's group section.

Using the API

For core-only installations, you need to make sure to use the correct server name and port number provided by your system administrator.

The code snippet below uses the API to convert XML to PDF using a template stored on the NorthStar Essentials server. An XML string is sent to the NorthStar Essentials server and a PDF is received back:

String apiUrl = "https://api.example.com";
String apiKey = "898d6c1c-057f-4b8a-b429-c0bafa5a1ebf";
String downloadFolder = "C:/Temp/";
String fileName = "sample-xml2pdf.pdf";

// Authenticate
ApiClient client = new ApiClient();
client.setBasePath(apiUrl);
client.addDefaultHeader("Authorization", "Basic " + Base64.getEncoder().encodeToString(apiKey.getBytes()));

AuthorizationApi authorizationApi = new AuthorizationApi(client);
String sessionToken = authorizationApi.getToken().getAccessToken();
client.addDefaultHeader("Authorization", "Basic " + Base64.getEncoder().encodeToString(sessionToken.getBytes()));

System.out.format("Your token is: %s%n", sessionToken);

// Create RenderRequest
RenderRequestEntity renderRequest = new RenderRequestEntity();

InputSettings inputSettings = new InputSettings();
Template template = new Template();
template.setWorkspace("Default");
template.setPath("Bookstore Invoice\\Invoice.epr");
inputSettings.setTemplate(template);
renderRequest.setInputSettings(inputSettings);

String xml = "<?xml version=\"1.0\" standalone=\"yes\"?>" +
        "<root>" +
            "<Invoices>" +
                "<Invoice>" +
                    "<InvoiceProperties>" +
                        "<number>02116</number>" +
                        "<date>2016-06-10</date>" +
                    "</InvoiceProperties>" +
                    "<CustomerInformation>" +
                        "<name>Earl Library Co.</name>" +
                        "<address>1021 South Main Street,Seattle, Washington 92315</address>" +
                        "<email>sales@earlbook.com</email>" +
                        "<telephone>(206)321-2345</telephone>" +
                    "</CustomerInformation>" +
                    "<Products>" +
                        "<Product>" +
                            "<id>1</id>" +
                            "<name>Rendezvous with Rama by Arthur C. Clarke</name>" +
                            "<price>15</price>" +
                            "<quantity>3</quantity>" +
                            "<total>45</total>" +
                            "<description>An all-time science fiction classic, Rendezvous with Rama is also one of Clarke's best novels--it won the Campbell, Hugo, Jupiter, and Nebula Awards.</description>" +
                        "</Product>" +
                    "</Products>" +
                    "<Comments>" +
                        "<comments>Contact us with any questions you may have.</comments>" +
                    "</Comments>" +
                "</Invoice>" +
            "</Invoices>" +
        "</root>";

Input input = new Input();
input.setInputFormat("xml");
input.setSource("data:application/xml;base64," + Base64.getEncoder().encodeToString(xml.getBytes()));
renderRequest.setInput(input);

renderRequest.setPdfOutput(new PdfOutput());

DirectRenderApi renderApi = new DirectRenderApi(client);

// Send the Request
File response = renderApi.render(renderRequest);

// Write the file
byte[] data = Files.readAllBytes(response.toPath());
OutputStream out = new FileOutputStream(new File(downloadFolder + fileName));
out.write(data);
out.close();

System.out.format("File %s downloaded ok%n", downloadFolder + fileName);

Note

The API Reference entities and methods uses a simplified model. You will need to use setters and getters when working with entities, just like it is used in the above example.

General Notes

This section will cover the common errors encountered when using the REST APIs, along with some information about each of them and the accepted time standards.

Error handling

Each API method can throw error and attempts to return appropriate HTTP status codes. Additional info is included in the body of the response, JSON-formatted.

Example: 

//400 BadRequest
{
    "Message": "Required parameter 'Path' not found."
}

Code Text Description
200 OK Success!
201 Created Resource created. Usually, the response body represents the newly created resource.
204 No Content Request processed. Response is intentionally blank e.g. DELETE operations.
400 Bad Request The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized Missing or incorrect credentials.
403 Forbidden The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why. This is usually because of the current authenticated user not having permission to manage the resource.
404 Not Found The URI requested is invalid or the resource requested, such as a user, does not exist.
410 Gone This resource is gone. Used to indicate that an API endpoint has been turned off.
415 Unsupported Media Type The payload is in a format not supported by this method on the target resource. The format problem might be due to the request's indicated Content-Type or Content-Encoding, or as a result of inspecting the data directly.
500 Internal Server Error Something is broken. Additional explanation is included in the response body.

Dates and durations

This section helps you pay attention when work with date and time and what these parameters do by the time they leave your API platform. NorthStar Essentials solution is to use ISO standards for the time representation.

All dates in the API are strings in the ISO 8601 DateTime format: 

"2017-01-26T11:29:35Z"

All durations in the API are string in the ISO 8601 Duration format: 

"PT1.52S"