- Sales1-877-762-2519
- Support Lines
- North America1-877-862-2519
- Australia1800 223 198
- United Kingdom+44 (0) 80 0048 8810
- Other Countries+800-6622-5192
Try Replicon Free For 14 Days
Get Started With A Free TrialUse 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.
| ||||||||||||
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.
| |||||||||||||
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" ] }
| ||||||||||||
The RepliConnect API is accessed using your Replicon URL, appended with: /remoteAPI/remoteapi.ashx/<version#>/ For example, the RepliConnect version https://na1.replicon.com/ABC/remoteAPI/remoteapi.ashx/8.29.66/ Append /testmode to this URL to access the API in test mode.
| |||||||||||||
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:
If the output format is JSON:
| ||||||||||||
Understanding RepliConnect API Authentication | RepliConnect API support two authentication approaches:
All communication with the API is done through POST. The content type for all posts should be: content type = application/JSON |
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:
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:
A characteristic of an object that you can set directly.
A characteristic of an object that references another object. A relationship can only be set by defining the related objects.
Calculates object settings that are too complicated to define by assigning properties or relationships.
A group of property options. Only one can be valid at a time for an object.
A type of request you can make using RepliConnect. There are four types of actions: Query, LoadIdentity, Create, and Edit.
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. |
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:
|
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)); } } }
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"] }