Enterprise API Guide

Notes

This documentation describes the Application Programming Interfaces (API v2) for the NorthStar CCM Platform version R2026 (formerly EngageCX 14/Ruby) and later.

Introducing NorthStar CCM API 2

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

The following features are matching the MHC NorthStar CCM solution:

• Create Digital Experience Documents (DXD) for mobile devices and desktop computers
• Use interactive drill-down and intelligent analytics features
• Deliver personalized messages and marketing ads
• Track how end-customers are reading their documents
• Control document assembly and automation using workflows.
• Use the online version of the MHC Studio for improved collaboration.
• Create documents interactively by filling out forms.
• Create print streams for high-volume printers (Postscript, PDF or AFP).
• SMS, Email with CID images, PDF-X, HTML5 (responsive/interactive), JPEG.
• Distribute documents to end-customers via print, email, etc.
• Additional data integration (Salesforce, MS Dynamics).

MHC NorthStar CCM provides the following APIs:

• JavaScript for web programmers through the inclusion of EngageCX.Client.2.0.js
• C# for .NET programmers by adding a reference to the EngageCX.Client.NET.dll assembly
• Java for Java programmers through the EngageCX.Client.JAVA-2.0.0.jar package

Notes

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

• For MHC NorthStar CCM installations, the ports default to 80 (HTTP) and 443 (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.

To access the Live REST API Inspector:

• Sign in to the NorthStar CCM Enterprise Home website and access the Developer module.
• Select the Software tile under the Tools group.
• Click on the REST API Inspector tile and you will be redirected to the Live REST API page.

Getting Started

Authentication

NorthStar CCM uses API keys in order to authenticate requests made by clients. To manage API keys, from your NorthStar CCM home page, access the Developer module/API Keys.

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

Single Sign-On

SSO enables users to access all of their enterprise applications by signing in one time for all services. We provide a Security Assertion Markup Language (SAML)-based SSO API that you can use to integrate into your IdP (Identity Provider).

Read more about NorthStar CCM SSO here.

Template management

NorthStar CCM uses document templates (.epr files created in NorthStar CCM Design Studio) to merge data points with layout and create personalized documents. This process is called document composition. Within NorthStar CCM Platform, templates are managed in a high-performance repository with versioning capabilities. Use the top-left menu to access your workspaces.

Using JavaScript API

Including the library

The JavaScript API is referenced through EngageCX.Client.2.0.js. To download the API, from your NorthStar CCM home page, access Developer module/Software.

<html>
    <head>
        <script src="https://nsccm.example.com/EngageCX.Client.2.0.js"></script>
    </head>
<body>
    <script>
    // JavaScript code that uses the EngageCX API
    </script>
</body>
</html>

Using the API

The example below uses JavaScript to convert XML to PDF using a template stored on the NorthStar CCM server. An XML string is sent to the NorthStar CCM server and a PDF is received back:

// Wait for the API to initialize
eosAPI.ready(function(){
    // Authenticate using an API key
    eosAPI.authorize("API:59e80576-19e5-4808-98c0-cf2c9da055ea")
    .catch(function(error){
        // Handle any authentication errors here
        alert("Authentication failure: " + error.response.statusText);
    })
});
// Wait for authorize() to complete
eosAPI.authorized(function(){
    // Render an xml to pdf using a template
    eosAPI.DirectRender.Render({}, {
        responseContentType: 'application/pdf',
        requestBody:  {
            InputSettings: {
                Template: {
                    Workspace: "Default",
                    Path: "Retail/Bookstore Invoice/Invoice.epr"
                }
            },
            Input: {
                InputFormat: "xml",
                Source: '<?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>'
            },
            PdfOutput: {}
        }
    })
    .then(function(response) {
        // PDF rendered and received. You can use response.data to retrieve the PDF bytes, 
        // however for this sample the previewResponse utility is used 
        // to quickly preview the response bytes in a new window
        eosAPI.Util.previewResponse(response);
    })
    .catch(function(error){
        // Handle any render errors here
        alert("Render error: " + error.response.obj.Message);
    });
});

Notes

• The NorthStar CCM JavaScript API uses Promises.
• The response's obj property contains the deserialized response.
• The response's data property contains the response bytes if it's binary.
• The response's status property contains the HTTP status code.
• Before using the API you must wait for it to become ready either by using .ready or .authorized wrappers.
• If you're getting the sessionToken using your own backend you can use .authorizeWithToken utility instead of authorize.
• After authorization is complete, the session token is available via eosAPI.sessionToken.

Using .NET API

Downloading the API

In .NET you need to include a reference to EngageCX.Client.NET.dll. To download the API, from your NorthStar CCM home page, access Developer module/Software.

Using the API

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

string apiUrl = "http://nsccm.example.com";
string apiKey = "API: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);

    // Create a new render request
    RenderRequestEntity request = new RenderRequestEntity()
    {
        InputSettings = new InputSettings()
        {
            Template = new Template()
            {
                Workspace = "Default",
                Path = @"Retail\Bookstore Invoice\Invoice.epr"
            }
        },
        Input = new Input()
        {
            InputFormat = "xml",
            Source = "<?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>"
        },
        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

Downloading the API

In Java you need to include a reference to EngageCX.Client.JAVA-2.0.0.jar. To download the API, from your NorthStar CCM home page, access the Developer module/Software.

Using the API

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

String apiUrl = "http://nsccm.example.com";
String apiKey = "API: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("Retail\\Bookstore Invoice\\Invoice.epr");
inputSettings.setTemplate(template);
renderRequest.setInputSettings(inputSettings);

Input input = new Input();
input.setInputFormat("xml");
input.setSource("<?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>");
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);

Java SDK Notes

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

General Notes

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

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"