Revision as of 16:35, 22 June 2018

Please note that this page is currently under construction. There is more information to come.

Overview

SmartSimple's SmartConnect API provides a relatively easy to use method of integrating SmartSimple information with other web services and systems. It is a RESTful API and loosely follows the principles of REST integration.

This API uses industry standard JSON syntax and constructs. If you are not familiar with JSON you should take a look at the following tutorial before venturing much further in this topic.

Prerequisites

• This API is only available for SmartSimple environments on the November 2015 release or later. We recommend you upgrade to the latest available release for the most up to date API functionality.

Configuration - Essentials

Initial Setup

You will need an active SmartSimple user account in order to make any API calls. There are two modes of operation for this API, and if you are planning on making remote calls you will first need to create and activate an API type user.

• Active session: Where a user is already logged into SmartSimple with an active session and makes an API call from their web browser, e.g. an AJAX call. The user's existing session is used to authenticate the API call.
• Remote call: Where an external system makes an API call. For this method, a user account of type API Access is required to authenticate the API call.
  

  Roles and access setting of a user to be used for remote calls.

Function Definition

In order to use the API, you must first define the set of functions you wish to make available within SmartSimple. This is an added layer of security that lets you limit the available functions as well as field sets that you wish to expose through the API.

1. Within your SmartSimple instance, define an API function within the Global Settings -> Integrations -> SmartConnect API screen.
2. In this screen you will find options for Record Type, Action Type, and Field List that define respectively, the type of record, the action to perform, and the field list that will be exposed for this function.
3. After saving your function, take note of the API Token as you will need to include this in your API calls to identify this pre-defined function.

Here is a more detailed look at creating SmartConnect functions.

Field List Syntax

The Field List option within the function configuration is used to define which fields are retrievable through the function call. This is a free form text box in which you will need to construct your field list with the following syntax:

Usage

Make sure JSON API functions were created in the instance before you can use them.

First, here are some rules to be aware of when calling the API functions.

• All update functions have a jsonrset parameter. When updating a record, the jsonrset must include all fields in the field list to ensure it works properly. If the value is not being changed, set it to the current value.
• If updating a new field, that field must also be added to the field list within the function configuration.
• Date fields in the jsonrset should be formatted as yyyy-mm-dd.
• Fields with pre-defined options (eg. drop down, check box, etc.) can be set by giving the stored value of the desired option, not the display caption
• The update functions are also used to create new records. This can be done by setting the recordid to 0. The response will then display the recordid of the record created.

Posting Endpoints

To make an API call you will need to post to the appropriate endpoint which will simply be based on the Record Type of the API function. The general endpoint will be in the form of:

/API/APIVersion/recordtype/

The full list of endpoints is below.

Message Body

The message body that you post will need to include various parameters depending on the Record Type and Action Type being used. The required and optional parameters will be listed for each different function on the configuration page of each SmartConnect function.

At minimum, you will always need to include:

• url: String containing the URL to which the request is sent
• apitoken: Encrypted token generated and associated to each SmartConnect function.

If you are making a remote call from an external system you will also need to include:

• username: The email address of an active API type user account.
• password: The corresponding password to the above user account.
• companyid: The root companyid of your SmartSimple instance. This is the companyid of the organization at the root of your instance.
• alias: The web alias of your SmartSimple instance. This will typically be the leading portion of your instance URL, and can be found in your Global Settings -> Branding configuration. E.g. for https://example.smartsimple.com the alias would be 'example'.

Here is a more detailed look at using SmartConnect functions.

Sample call within SmartSimple instance:

function api_call() {
    $.ajax({
            method: "POST",
            type: "POST",
            url: "/API/1/levelone/",
            data: {
                apitoken: "QlwYYlJERHVASmlfXWtTWklbXEt9UHpmDw4~",
                recordid: 1234567,
            },
            dataType: "html"
        })
        .done(function(data) {
            json = JSON.parse(data);
        });
}

Sample Remote call outside of Smartsimple instance:

function api_call() {
    $.ajax({
            method: "POST",
            type: "POST",
            url: "/API/1/levelone/",
            data: {
		username: username,
		password: password,
		companyid: 825646,
		alias: api
                apitoken: "QlwYYlJERHVASmlfXWtTWklbXEt9UHpmDw4~",
                recordid: 1234567,
            },
            dataType: "html"
        })
        .done(function(data) {
            json = JSON.parse(data);
        });
}

POST Response

With every successful request a HTTP status of 200 is returned along with a JSON response body that contains the record field data.

For record updates and creation, the response body will return the Record ID and a status of "Updated Successfully".

Sample Response format for Update:<br />
{
   "records":[
      {
         "recordid":"6048788",
         "recordindex":1,
         "status":"updated successfully"
      }
   ],
   "message":{

   }
}

Sample Response format for GET/LIST based on configured field list:

{
   "records":[
      {
         "sf_Description":"0959-3985",
         "sf_Transaction ID":"6048788",
         "sf_Created Date":"2015-07-23 11:03:17",
         "sf_End Date":"2015-07-23 11:03:17",
         "sf_Subject":"API Test",
         "sf_Object ID":"0",
         "sf_Start Date":"2015-07-22 00:00:00",
         "sf_Modified Date":"2018-05-09 11:14:58",
         "sf_Type":"Publications",
         "sf_Created By":"SmartSimple Support",
      }
   ],
   "message":{

   }
}

Error Messages

For failed requests, SmartSimple returns HTTP 4xx status codes.

The most common case is HTTP 401 Unauthorized which could indicate one of the following:

• Invalid authentication credentials provided
• User Account type is not of "API User"
• If performing remote calls, make sure the companyid parameter is correct

If the request is successful and the response is blank, review the following troubleshooting steps:

• Ensure the apitoken parameter is correct
• If updating, ensure the recordid is correct
• Review the post endpoint url is pointing to the correct resource

Update Behaviour

Please note when performing updates that the system behaviour will be similar to that of saving the record in the regular browser interface. Namely, the following will occur:

• Any existing and applicable template formulas will be triggered and run after a record update.
• Any existing and applicable workflows will be triggered and run after a record update.
• Any existing and applicable status-triggers will run for any status change after a record update.

Configuration - Advanced

Appendix

Creating SmartConnect functions

SmartConnect functions are created for each individual instance of SmartSimple. You can create multiple functions of the same action if needed, depending on the field list returned.

See Creating and Managing SmartConnect Functions for a more detailed look at creating functions.

Standard Field Names

See SmartConnect Standard Field Names for a list of available Standard Fields that you can reference along with update restrictions.

The standard fields available for reference varies on the Record Type selected in the API call.

Options and Settings

Available Record Types

Available Action Types

The following is a full list of available actions. Please note that not all actions will be available for all record types.

SmartConnect Examples

See our interactive demonstration page for a demo and live sample of how the API works. This page is connected to a specific demonstration instance containing sample data.

We strongly encourage you to review this page in order to gain a better understanding of the syntax and functionality of the API.

See API examples for a sample list of SmartConnect calls.