Getting Started with the RepliConnect API

Use the RepliConnect API to access and edit your Replicon data, and to create custom integrations with third party software, such as accounting, payroll or billing applications.

Enabling RepliConnect API

User-level access to RepliConnect is enabled by default for all customers. If you require full-level access to RepliConnect, contact Replicon Support and they can enable this level of access for you.

There are no additional system requirements for using the API, beyond the standard Replicon requirements.

RepliConnect API is only available if you are using Replicon version 8.15 or higher.

Assigning Permissions

Before using RepliConnect, you will need to assign permission to any users who need to access the API. There are two API permissions, located in the Integration section of permission profiles:

Assign RepliConnect API permission to give the user access to the API. You can also assign users API Test page access permission, which allows access to the API test page located within the Replicon interface.

Refer to the Permissions topic in Replicon's online help if you need information on how to assign permissions.

If you have full API access, an additional API permission called Can view ALL system data is available. Assigning this permission gives the user access to all data in your system. Therefore, to ensure data security, we recommend that you assign this permission to an administrator or to a dedicated API account only.

Understanding Security Contexts

To use RepliConnect, you'll need to provide an HTTP header named X-Replicon-Security-Context. The header value you provide indicates the security context under which API requests will operate.

Security contexts define how the application interprets user actions in different scenarios. For example, an account with Historical Timesheet Approve permission can approve any timesheet from the Historical Timesheets page (one scenario); but the same account may not be able to approve timesheets from the Timesheet Approvals page (a second scenario). Security contexts can change how functions such as validation rules, security rules, and operations are applied through the API.

RepliConnect API supports two security contexts: User and Approver. The User context represents typical user actions, such as using timesheets, expense sheets and time off bookings, while the Approver context allows you to perform approval operations.

For example, you would indicate the User security context using the following header:

POST /companyABC/RemoteApi/RemoteApi.ashx/8.29.66/ HTTP/1.1
Host: na1.replicon.com
Content-Type: application/json
Content-Length: 126
X-Replicon-Security-Context: User

{
  "Action": "Query",
  "DomainType": "Replicon.Domain.User",
  "QueryType": "UserByLoginName",
  "Args": [
    "admin"
  ]
}
Applications developed before the introduction of the X-Replicon-Security-Context header can operate without a security context, providing the Can view ALL system data API permission is enabled. This permission is only available with full access to RepliConnect; contact Replicon Support to enable full access.

Accessing RepliConnect API

The RepliConnect API is accessed using your Replicon URL, appended with:

/remoteAPI/remoteapi.ashx/<version#>/

For example, the RepliConnect version URL for company ABC would be:

https://na1.replicon.com/ABC/remoteAPI/remoteapi.ashx/8.29.66/

Append /testmode to this URL to access the API in test mode.

The version number for the latest release of RepliConnect is 8.29.66.

Accessing RepliConnect via a Static URL

 

Replicon provides a web service that you can use to retrieve the latest RepliConnect URL from a static location. This service may be useful, for example, in integration applications that require the end-user to enter the company key, for companies with multiple data centers which results in multiple API URLs, or to allow continuity if the RepliConnect URL ever changes.

The fetch URL service is located at:

http://services.replicon.com/FetchRemoteApiUrl.ashx?CompanyKey=ABC&Version=8.29.66

That web service call would reply with the following URL on a single line in plain text:

https://na1.replicon.com/ABC/remoteAPI/remoteapi.ashx/8.29.66/

The Fetch URL service also optionally supports a JSON formatted request and response:

POST /FetchRemoteApiUrl.ashx HTTP/1.1
Host: services.replicon.com
Content-Type: application/json

{
    "CompanyKey": "ABC",
    "Version": "8.29.66"
}

By default, when posting a JSON object to the service, it will reply in JSON:

200 OK
Content-Type: application/json

{
    "Status": "OK",
    "Value": "https://na1.replicon.com/ABC/remoteAPI/remoteapi.ashx/8.29.66/"
}

The output format can be controlled explicitly with the "output" parameter, either in the HTTP request parameters or the JSON object. The available options are "JSON" or "text".

This service is flexible; you can use any combination of posted JSON variables or query parameters.  However, both "CompanyKey" and "Version" are required fields; if either is missing, the service will reply with an error.

If the output format is plain text:

HTTP Status Code

Error

400 (BadRequest)

One or more of the required fields is missing

403

The specific CompanyKey could not be found

500

An unexpected server error occurred, or the service is down

If the output format is JSON:

HTTP Status Code

Error

200

All errors. The Status Code field will indicate either "OK" or "Error".

Understanding RepliConnect API Authentication

RepliConnect API support two authentication approaches:

  1. Sending login name and password with every request via basic HTTP authentication.
  2. Session based login. For more details, refer to the Actions page.

All communication with the API is done through POST. The content type for all posts should be: content type = application/JSON

Back to top

Using the RepliConnect API

Understanding JSON Architecture

The RepliConnect API is based on the JSON text-based standard. JSON is language-independent, and can be used with practically any programming language.

Here are some useful JSON resources:

Understanding Key Terms

The following terms are used in the documentation:

  • Object

A programming entity that corresponds to a functional concept in Replicon. Also referred to as domain object or type.

Each object is defined by the following elements:

  • Property

A characteristic of an object that you can set directly.

  • Relationship

A characteristic of an object that references another object. A relationship can only be set by defining the related objects.

  • Operation

Calculates object settings that are too complicated to define by assigning properties or relationships.

  • Enum

A group of property options. Only one can be valid at a time for an object.

  • Action

A type of request you can make using RepliConnect. There are four types of actions: Query, LoadIdentity, Create, and Edit.

  • Exception

An action that did not complete as expected.

Writing your Code

Select the links on this page's side menu for information on all objects you can work with using RepliConnect. Examples are included.

Examples of the actions and predefined operations you may use, and of exceptions you may encounter, are also available. Plus, examples of complete requests using C# and Ruby, including authentication and verification code, is given below.

Testing your Code

You can choose to connect to RepliConnect in 'test mode'. When you access the API in test mode, any changes you make are automatically rolled back and are not committed to the database.

There are two ways to connect using test mode:

  1. By appending /testmode to your RepliConnect access URL.

  2. By accessing the API Test Interface within Replicon. To use the test mode, within Replicon, select Integration > RepliConnect API > Test Interface. Then, from the Test Mode drop-down, select Rollback.

Back to top

Example of a Complete Request using C#

This script demonstrates how to submit a Query request to return all users using C#.

using System; 
using System.IO; 
using System.Net; 
using System.Text; 
using Newtonsoft.Json; 
 
namespace RepliConnectExample 
{ 
    class Program 
    { 
        // Modify these to point at your Replicon instance 
        private const string apiUrl = "https://na1.replicon.com/a/RemoteAPI/RemoteAPI.ashx/8.29.66/"; 
        private const string companyKey = "CompanyABC"; 
        private const string loginname = "admin"; 
        private const string password = "passw0rd"; 
 
        private static readonly JsonSerializer jsonSerializer = new JsonSerializer(); 
 
        static void Main(string[] args) 
        { 
            // Fetch all users from the API 
            var apiAction = new JavaScriptObject(); 
            apiAction["Action"] = "Query"; 
            apiAction["QueryType"] = "UserAll"; 
            apiAction["DomainType"] = "Replicon.Domain.User"; 
            apiAction["Args"] = new JavaScriptArray(); 
            apiAction["SortBy"] = new JavaScriptArray() { "LastName", "FirstName" }; 
 
            foreach (object userObject in GetApiValues(apiAction)) 
            { 
                // Print out the user's names 
                var user = (JavaScriptObject)userObject; 
                var userProperties = (JavaScriptObject)user["Properties"]; 
                Console.WriteLine("{0}, {1}", 
                    userProperties["LastName"], 
                    userProperties["FirstName"]); 
            } 
        } 
 
        // Perform an API request, verify that the request completed 
        // successfully, and return the objects received. 
        private static JavaScriptArray GetApiValues(object apiRequest) 
        { 
            var response = (JavaScriptObject)PerformApiRequest(apiRequest); 
            var status = (string)response["Status"]; 
            if (status != "OK") 
                throw new Exception( 
                    String.Format("Expected Status OK, but was {0}", status)); 
            return (JavaScriptArray)response["Value"]; 
        } 
 
        // Do the dirty work of performing an API request 
        private static object PerformApiRequest(object apiRequest) 
        { 
            var request = (HttpWebRequest)WebRequest.Create(apiUrl); 
 
            request.Credentials = new NetworkCredential(companyKey + "\\" + loginname, password); 
            request.PreAuthenticate = true; // send auth on first request 
            request.Method = "POST"; 
            request.ContentType = "application/json; charset=utf-8"; 
            request.Headers.Add("X-Replicon-Security-Context", "User"); 
 
            // Send API request in JSON format 
            using (var requestStream = request.GetRequestStream()) 
            using (var writer = new StreamWriter(requestStream, Encoding.UTF8)) 
                jsonSerializer.Serialize(writer, apiRequest); 
 
            // Receive API request and convert into JSON objects 
            using (var response = (HttpWebResponse)request.GetResponse()) 
            using (var responseStream = response.GetResponseStream()) 
            using (var reader = new StreamReader(responseStream, 
                Encoding.GetEncoding(response.CharacterSet))) 
                return jsonSerializer.Deserialize(new JsonReader(reader)); 
        } 
    } 
}

Back to top

Example of a Complete Request using Ruby

This script demonstrates how to submit a Query request to return all users using Ruby.

require 'net/http' 
require 'net/https' 
require 'json' 
require 'uri' 
 
# Modify these to point at your Replicon instance 
$url = URI.parse("https://na1.replicon.com/a/RemoteAPI/RemoteAPI.ashx/8.29.66/") 
$companyKey = "CompanyABC" 
$loginname = "admin" 
$password = "passw0rd" 
 
# Do the dirty work of performing an API request 
def perform_api_request(query) 
    request = Net::HTTP::Post.new( 
        $url.path + ($url.query != nil ? ("?" + $url.query) : ""), 
        initheader = { 
            "Content-Type" => "application/json", 
            "X-Replicon-Security-Context" => "User"}) 
    request.basic_auth($companyKey + "\\" + $loginname, $password) 
    request.body = JSON.generate(query) 
 
    server = Net::HTTP.new($url.host, $url.port) 
    server.use_ssl = $url.scheme == "https" 
    response = server.start { |http| http.request(request) } 
 
    http_code = response.code.to_i 
    if http_code != 200 
        puts response.body 
        raise "Expected success code 200, but was #{http_code}" 
    end 
 
    return JSON.parse(response.body) 
end 
 
# Perform an API request, validate that Status is OK, and return the Values 
# from the API query. 
def get_api_values(query) 
    retval = perform_api_request(query) 
    if retval["Status"] != "OK" 
        puts response.body 
        raise "Expected status OK, but was #{retval["Status"]}" 
    end 
    return retval["Value"] 
end 
 
# Fetch all users from the API 
users = get_api_values({ 
    "Action" => "Query", 
    "DomainType" => "Replicon.Domain.User", 
    "QueryType" => "UserAll", 
    "Args" => [], 
    "SortBy" => [ "LastName", "FirstName" ] 
}) 
 
# Print out the user's names 
users.each { |user| 
    puts user["Properties"]["LastName"] + ", " + user["Properties"]["FirstName"] 
}

Back to top