API documentation

The Greentree API (application programming interface) provides a standard integration medium which can both read and write data in the Greentree Jade database. 

The Greentree API aims to cover the breadth and depth of features available in Greentree and  make them accessible from external systems and interfaces.  There is too much functionality to be developed and released in one go, as a result functional areas will be developed and released based on demand.

Whilst other integration technologies do exist for Greentree (including FREE, SOAP, JHP and selective data import/export functions), they are quite restrictive in their accessibility (FREE requires COM, SOAP access can be awkward and is very heavy, data imports are not suitable for real time integration), are limited to a subset of Greentree features .

Graphical presentation of Greentree API

How Does It Work ?

The Greentree API is a RESTful HTTP interface. 

In a nutshell, this means that you can use descriptive URL’s to access “things” in Greentree.  The structure of the URL’s is a vital part of the API and assists in its discoverability.  The transport mechanism is HTTP which makes it accessible from almost any platform and technology.  The standard HTTP verbs used by web servers are also used to determine what you want to do with the data (GET is used to read, POST is used to write, DELETE is used to delete).  Based on this, the same URL can be used with different verbs to achieve different behavior.

The Greentree API itself acts as a web server and services the queries against the database.  There is no requirement for IIS or any other web server technology.

The basic URL structure of an API call is as follows:

http://<server><port>/<company>/<entity>/<identifier>

The order of these parameters is important, they MUST be in this sequence.

An example of this call would be:

http://greentree.site.com:9000/01/SOPackingSlip/24333.01

• A GET request on this URL would return the details of the Pack Slip with a reference 24333.01. 
• A POST request on this same URL would accept a packet of data to update Pack Slip with a reference 24333.01.
• A DELETE request on this URL would delete the Packing Slip with reference 24333.01

Parameters

Following the base URL, you can append various query parameters to influence the behaviour of the API call.  Most of these parameters are specific to the particular request, however some of them are common amongst the various API calls.  The query parameters are passed across with the URL and preceded by a "?" character, which separates the base URL from the parameters.  Following this are key=value pairs, which can be separated by "&" if multiple query parameters are required. 

A GET request with no <identifier> will result in a list of the particular entity being requested. 

GET requests like this are capped at 100 entities per request, but can be paged using the query parameters “page” and “pageSize”.  In this case you can continue to increment “page” after each call, until the resulting packet returns less than “pageSize” entities.

An example of this which will return the first 20 Packing Slips in the Greentree company 01 is:

http://greentree.site.com:9000/01/SOPackingSlip?page=1&pageSize=20

An example of not specifying page size which will return the first 100 Packing Slips in the Greentree company 01 is:

http://greentree.site.com:9000/01/SOPackingSlip?page=1

A POST request with no <identifier> will add a new <entity> to the Greentree company.  As a general rule as a client of the API you cannot specify the <identifier> for a newly created entity, as it is preferred to allow Greentree to allocate these.  Note there are exceptions to this which will be documented with their entity.

Global Search

Added in 2020.1 was the ability to access the Global Search functionality of Greentree.  All endpoints support the GET command to fetch a list of records using the query parameter of "globalSearch".

An example of this which will return any Customers with matching data from the Global Search configuration

http://greentree.site.com:9000/01/Customer?globalSearch=041

Authentication

The Greentree API used “Basic Authentication” to allow access to the database.  The authenticated user is a regular Greentree user, based on a typical Greentree username and password configuration. 

In conjunction with this each call to the API must provide an API key.  This can be a parameter of the URL (which is handy when using a web browser), or via a HTTP header if accessing programmatically.  The ApiKey is simply the sites Greentree serial number.

An example of passing the API Key via the URL:

http://greentree.site.com:9000/01/SOPackingSlip?page=1&pageSize=20&ApiKey=23440933

If passing as a HTTP Header:

ApiKey=34440933

Greentree Configuration

API configuration

The Greentree API reads its configuration options from the jadegt.ini file at startup.

Debugging and Tracing

Introduced in Greentree 4@11 was support for logging API calls at the server to observe what is being called and what is being responded, this can be invaluable when diagnosing problems.  This is configured through the jadegt.ini file in the JadeLog section, and is queried in real time, which means you don't have to stop and start the API service as you turn it on/off.  We do not recommend leaving it turned on in a production site for any length of time as it will generate log files that will eat up disk space.  The file generated will be named along the lines of apilog.log and will be found in the folder defined by the LogDirectory setting which is also contained in the JadeLog section of the jadegt.ini file.

Starting as its own service

Running the API as it's own service cannot be done from Greentree Version 2021.4 and above.

The API can be configured as its own service on the same machine as the database server, or on another machine if desired.  In order to register the service a Windows shortcut or command/batch file can be created as described below.

The nodeName and nodeNameDescription determine what appears in the Service Control Manager and can be changed to anything that makes sense.  If you are updating your Greentree batch files to Stop/Start the services manually, you can "net start <nodeName>" and "net stop <nodeName>". 

Starting as part of the database service

To start as part of the database service simply add the following line to the [JadeServer] section (where <n> is the next available number) :

ServerApplication<n>=ApiSchema,ApiStartup

Data format

The HTTP Headers are used by the API to determine the format of data coming in during a POST, and the format to return in the response.  Of particular relevance are the Content-Type and Accept headers.  Typically these should be “text/xml” or “application/xml” when XML is used as the data format for transfer and  “application/json” when sending and receiving JSON (handling of POST data in application/json supported from Greentree 4@8-5).

Typical header could look like this:

Accept: application/xml;q=0.9,*/*;q=0.8
Authorization: Basic c3VwZXI6c3VwZXI=
Content-Length: 3616
Content-Type: text/xml; charset=UTF-8

Attachments

In Greentree attachments can be added to any object, as a result the API provides the ability to :

• Query the attachments for a particular entity
• Download an attachment from an entity by its name
• Upload an attachment to an existing entity

For any GET request, you have the option to pass a query parameter on the URL of "includeAttachments=true", this will include in the response a collection of attachments in the format of :

To download an actual attachment for an entity you pass a query parameter on the URL of "action=attachment&name=<name of attachment>".  Using the above as an example which is from StockItem A0002, I can download the first attachment using the following URL :

http://greentree.site.com:9000/01/StockItem/A0002?action=attachment&name=desktop.jpg

To upload an attachment submit a POST request to the entity you wish to attach to with a query parameter on the URL of "action=attachment".  The content must be posted as "multipart/form-data" and an entire file can be uploaded to Greentree.  The attachment name and file name are taken from the Content-Disposition segment of the posted form data.  Note that the "name" is defined by the key for the uploaded file.

Upload modifiers.

Sticky Notes

In Greentree sticky notes can be added to any object, as a result the API provides the ability to :

• Query the Sticky Notes for a particular entity.
• Create / Update Sticky Notes for a particular entity (2020.1)

For any GET request, you have the option to pass the following query parameters on the URL to include in the response a collection of Sticky Notes in the format below.  

Sticky Note Modifiers:

Note that neither confidential nor inactive notes are able to be retrieved via the API.

For any POST request you can include the same structure as above as part of the POST data to create/update Sticky Notes.  

To update an existing Sticky Note you must include the OidString, that is used to locate the actual Sticky Note to update and it will be cross checked against the containing entity to ensure you do not update a Sticky Note for another entity.  

Plugin Properties

(Available 2020)

In Greentree Plugin Properties (including Dynamic Properties) can be added to any object, as a result the API provides the ability to include the Plugin Properties in the returned data

For any request, you have the option to pass the following query parameters on the URL to include in the response a collection of Plugin Properties in the format below.  

Plugin Property Modifiers:

Sorting GET requests

(Available 2021 as preview)

The API is adding the ability to sort the result set, initially on ARInvoice and then rolling through the rest of the endpoints.

Sorting can be performed on a GET request that returns a list of results.  Specification of the sort criteria is done as an incrementing integral list of property names on the URL, with the ability to include a matching parameter to sort in descending order.

The sort parameters can be combined with all the existing modifiers.

Sorting modifiers:

You can include any number of sort parameters, and you can also sort by reference properties.

Some worked examples :

• Sort AR Invoices by Payment Date in descending order
  • http://server:port/company/ARInvoice?sortBy1=paymentDate&sortDesc1=true

• Sort AR Invoice by Customer code
  • http://server:port/company/ARInvoice?sortBy1=myCustomer.code

• Sort AR Invoices by Branch, then by Document Date in descending order
  • http://server:port/company/ARInvoice?sortBy1=myBranch.code&sortBy2=documentDate&sortDesc2=true

Linked Objects

(Available 2020)

In Greentree generic Object Links can be created between any two objects, as a result the API provides the ability to include the Linked Objects in the returned data

For any request, you have the option to pass the following query parameters on the URL to include in the response a collection of Linked Objects in the format below.  

Linked Object Modifiers:

Approvals

In Greentree approvals can be added to any object, as a result the API provides the ability to :

• Query the Approvals for a particular entity.

For any GET request, you have the option to pass a query parameter on the URL of "includeApprovals=true", this will include in the response a collection of Approvals in the format of :

Approving a record

For any POST request to a specific object, you have the option to pass a query parameter on the URL of "action=approve" and a payload to state the approver, if not specified the API user is the approver :

Rejecting a record

For any POST request to a specific object, you have the option to pass a query parameter on the URL of "action=reject" and a payload to state the rejector, if not specified the API user is the rejector :

Clear Approvals for a record (post 2018.3 release)

For any POST request to a specific object, you have the option to pass a query parameter on the URL of "action=clearApproval".  There is no payload for this POST, and the result is to clear the approval status of the record.  Note this will remove all approval details from the specified record.

Reports 

(Available from 2019.2)

You can run any soft coded report (AHFormDefn) via the API by performing a POST operation to any entity using the query parameter of "action=report".  The payload for this POST is an AHFormDefn containing the report and values for the various parameters required to execute the report.

The response is a PDF as generated by the standard report processing, note that it is not at the mercy of the Task Queue.  

You have the ability to generate the report and have it attached directly against a record in Greentree.  If your POST is addressed to a particular instance you can include the <Attachment> detail as part of the payload, which as per the sample below includes 2 specific attributes:

Posting the below payload to http://server:port/01/CRMSVRequest/1021?action=report will run the report named "CRM SV Inventory Requirements" with a from/to parameters of 1021 and create an Attachment by the name of "My Report" which will replace an existing attachment called "My Report" should one exist, and it will also return the generated PDF as a response to my call.

Beware that some reports may take significant time to execute, and your call to the API may timeout prior to the completion of the report execution.  The report execution itself has a default timeout of 60 seconds as it waits for the report to complete, you can override this by passing a query parameter of "timeout=n" where n is a value in seconds.

A future enhancement to this might be to allow for asynchronous execution, having the API return a token that can be used to check the progress of the report, and ultimately then either cancel it, or retrieve the finished report PDF.