Welcome

Welcome to the CNH Developer Portal, the entrance to the CNH data ecosystem. Here you will be able to gain access to our two API suites, as well as our SDKs and plugins. The offerings available are:

  • AFS/PLM Connect API - This API endpoint and its supporting methods allow data sharing between your FMIS and the CNH data ecosystem by using an OAuth permissioning scheme.
  • ADAPT Plugin - A plugin to easily convert to and from the ADAPT data format.
  • Voyager 2 SDK - An SDK that allows data conversion to and from CNH’s CN1 / Voyager File format.

Participation and Process

CNH requires all applications that will use its APIs to pass a simple certification process before those applications become available for other CNH users (much like releasing an application on the iTunes app store). The process will involve an audit by CNH's software professionals, to ensure that any application being offered to our customers maintains the highest standards of quality.

The process of getting an app onto the Developer Portal App Store for other customers to use is fourfold: Sign-up, Register, Submit, and Release.

Application Life Cycle

Sign-Up

The first step in getting started with the CNH API offerings is to register an account and associate your account with a company. In order to access the full suite of functionality available on the Developer Portal, you must have both a verified account and be a member of a verified Company group. (If you are not a member of a Company already in the system, don't worry - you can create one during the process.)

Signing up for an account is simple. First, click the Login link in the upper right of the Developer Portal site. Then, on the popup, click Sign Up.

Sign Up

From there, you will be taken to a sign-up form. The form asks for your email, a password, and your first and last names. Be sure to use an email address associated with any company you wish your account to be automatically associated with.

Your password must be:

  • At least 8 characters long
  • Contain both lowercase and uppercase letters
  • Contain at least one number

Sign Up

Confirm Your Email

To establish a full account within the system and be able to log in, you must confirm your identity via the email address you provided when you signed up. You should receive an email within one hour of registering your account that contains a link to confirm your identity. Once you have confirmed, your account will be accessible.

Terms and Conditions

Upon first log in to the CNH Developer Portal, you will be presented with your account information, the opportunity to add more information such as phone contacts, and the Terms and Conditions of the Developer Portal. In addition, to progress further, you must agree to the Terms and Conditions, which pertain to the acceptable usage of the CNH Developer Portal offerings.

Google Account

You may also sign-up using your Google account, rather than your standard business email address. Signing in with a Google account, however, does limit access to the entirety of the CNH Developer Portal. You will have to manually request permission to join a company group within the system, and then the admin of your company group will have to approve your request in order for you to gain access to the full range of the CNH Developer Portal offerings.

Company

Existing Company

After confirming your email, we scan our system to see if you might be associated with a pre-existing company. This is done using the email you used to create your account (This is why registering with a Google account does not immediately grant you full access). If you received a direct invitation in an email to sign-up for the CNH Developer Portal, and clicked the link in that mail to begin the sign-up process, that will also indicate association with a pre-existing company. If one is found, we offer the option to associate your account with that company. This gives you access to register for any of the features that come with being part of a company group within the CNH Developer Portal (Data Sharing APIs, etc.).

If a company is not found, OR you choose not to associate yourself with any companies that are found, you will be given the opportunity to register a new company with the system, or simply associate your account with a generic “System Users” company maintained for individuals using the CNH Developer Portal. While you are not required to join the company indicated by your email or by your direct invite, you must be a part of a company in order to enjoy the full benefits of the CNH Developer Portal.

New Company

If you choose to register a new company, you will be directed to a form that allows you to enter company details. The following details are required:

  • Name
  • Corporate HQ Address (Street, City, State, Postal Code, Country)
  • Phone Number
  • Company URL

Once you have created your new company, you will be given access to the Developer Portal. From there, you will find a top navigation link to allow you to edit the company you have created, as well as manage any other users belonging to the company within the system.

Register

The next step in the development and release process is to register your app with CNH, via the Developer Portal.

To register your app, you may either click the link above, or navigate to your Account Dashboard and click Add App Submission. (For more information about your Account Dashboard, please see the later section on the topic.)

Registration Form

You will be presented with a form to fill out with details about your application. You will be asked to provide:

  • Application name
  • An application icon
  • Your application's landing page
  • Technical authorization details
  • A series of questions regarding HOW your application will interact with the CNH data ecosystem
  • Public or private nature of your FMIS
  • Tags relevant to your application for the CNH App Store

Once you have completed the sign-up process, you will have access to your staging environment client_id, client_secret, and API key.

API Keys

Your API key is a unique identifier for your app, and will be included with API calls to identify your app. Your client_id is your "username", and client_secret is the “password” that the AFS/PLM Connect API uses to authenticate your application. It is important that you never expose your client_secret in any action of your application.

The API key does not grant any of your users access to their CNH API data, however. It only allows and identifies the application ITSELF - the data it queries and posts belongs to your users, and it needs their specific user permissions as well.

Once your application has been submitted and passed its evaluation, you will receive your production keys.

How to Use Your API key

Once you have your client_id and client_secret, you’ll need to understand how to use it in your application to gain access. You include your API key in each call you make to the API by adding it to the header of your request, as in the below example.


public class APIHeader
    {
        public static HttpClient ClientInformation(string bearerToken)
        {
            HttpClient client = new HttpClient();

            // initializing the variable holding your key
            string subscriptionKey = "{your-api-subscription-key-goes-here}";
            client.BaseAddress = new Uri(StaticSettings.AddressINT);

            MediaTypeWithQualityHeaderValue contentType = new MediaTypeWithQualityHeaderValue("application/json");
            client.DefaultRequestHeaders.Accept.Add(contentType);
            client.DefaultRequestHeaders.Add("Cache-Control", "no-cache");
            client.DefaultRequestHeaders.Add("Ocp-Apim-Trace", "true");

            // Adding your key to the headers of the http request
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);

            // Adding the bearing token you get from the authentication process
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", bearerToken);
            return client;
        }
    }

Now you're ready to develop your application! For more help specifically regarding developing an FMIS using the Developer Portal offerings, please see our API specific tutorials and documentation

Submit

Once your app has been built and passed through your own quality process, you're ready to submit the app to CNH for review. Before you submit, however, you will want to verify that your app will pass the CNH quality bar for admission to the Developer Portal app store.

Quality Compliance Guidelines

How to Submit Your App

Submission for review is an easy process. First, navigate to your Account Dashboard. Once there, click on App Registrations on the left sidebar menu.

App Registrations

Once there, you will see a list of the applications that you have submitted as a user, and if you have permissions, any submissions made by your Company.

Application Dashboard

Find the app that you wish to Submit. You will notice that its status is Pending, indicating that you have not yet submitted it for review. Double click on the app's entry, and you will be taken to the Submission page for that app. Once there, you may check the details of your app (the same details you entered when you Registered for your keys), as well as Submit your app for testing. On the right side of the screen, you will find the button to Submit your app.

Submit For Testing

Once you have clicked the button to submit, if you return to the App Registrations page, you will notice that the status of your app has shifted to Testing. The testing process may take a few days - if you have not received an email response after one business week, please contact CNH or file a support ticket in your Account Dashboard.

What If My App Is Rejected?

If your app is rejected, you will receive an email notifying you. The email will also contain the criteria upon which the rejection was based. Once you have corrected the issues indicated in the email, you may submit your application again for consideration.

Release

Now that your application has been accepted, it only remains to release it to the App Store. By default, applications are not visible in the CNH App Store. If you wish your application to be available to other users, you must release it to the App Store.

Again, navigate to the Account Dashboard, and then to your App Registrations. Click on the entry for your application to return to its details page. On the details page, you will notice that the Testing section has been replaced with an App Store Visibility section. Simply click the button to publish your app to the App Store.

Unpublished Application

If at any time you wish to pull your application from the App Store, you may return to this same page, where you will find the button now allows you to remove your app.

Published Application

Account Controls

Keeping track of what stage your application is in the process of releasing it to the App Store, or in the case of an Adviser or Grower tracking who has access to what data, can be a tricky process. The Developer Portal makes this information easy to access and change with the controls offered on the top bar.

Account Controls

Edit My Profile

The Edit My Profile option hosts all of the functionality relevant to you as a personal users of the site. You may:

  • Edit your user information
  • Download stored data
  • View user activity

Edit My Company

The Edit My Company option hosts all functionality for managing a Company entity within the API offerings. You may:

  • Edit company information
  • Add or remove members

Account Dashboard

The Account Dashboard option hosts the registration and submission process, as well as the support functionality for the Developer Portal. You may:

  • Register your app to receive your application keys
  • Submit an application for evaluation
  • Publish your app to the App Store
  • Open a support ticket
  • View and manage open tickets