...
Graphical presentation of Greentree API
How Does It Work ?
The Greentree API is a RESTful HTTP interface.
...
http://<server><port>/<company>/<entity>/<identifier>
| Segment | Definition | Example |
|---|---|---|
| <server> | Server name or IP address | 203.44.22.12 or greentree.site.com |
<port> | Port that Greentree will listen on (default is 9000) | 9000 |
<company> | Greentree company | 01 |
<entity> | The type of object in Greentree you are referencing. This is usually the name of the Jade Class. | SOPackingSlip |
<identifier> | The primary key to identify the object you are referencing. Optional. | The reference of a Packing Slip – eg 243333.01 |
The order of these parameters is important, they MUST be in this sequence.
...
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".
...
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.
...
The Greentree API reads its configuration options from the jadegt.ini file at startup.
| Setting | Purpose | Default | Available |
|---|---|---|---|
| ListenPort | TCP port that the API will accept connections on. Default value is 9000 | 9000 | |
| QueueDepthLimit | The number of ready connections are waiting to be processed before another Worker Thread is started | 2 | |
| QueueDepthLimitTimeout | The number of seconds the queue will sit at its QueueDepthLimit before another Worker Thread is started | 2 | |
| WorkerIdleTimeout | The number of seconds that a Worker Thread has been sitting idle before it is shutdown. | 120 | |
| MaxWorkerThreads | The maximum number of worker threads to process incoming requests. If you are anticipating a lot of traffic, increase this figure to handle more concurrent connections. | 5 | |
| MinWorkerThreads | The minimum number of worker threads to process incoming requests. When traffic has ceased, all worker threads will be terminated leaving behind MinWorkerThreads. To get faster ramp up time when traffic arrives, increase this value | 1 | |
| RetainXmlWhitespace | If set to true, CR, LF, CRLF and TAB characters will be retained in text values posted through in XML data. If left out or set to false, these characters will be converted into spaces. Note that such values should be encoded when posted through eg:
| false | |
| CallDurationLogTrigger | Used in conjunction with the Debugging and Tracing to highlight in the log files API calls that are taking a long time The value is in seconds Calls that exceed this value are prefixed with *** when written to the log file | 0 | Post 2018.3 |
| ReadTimeout | Reading data sent to the API respects the Content-Length, on occasion the amount of data sent is less than the Content-Length, in which case the API sits waiting indefinitely for the remaining bytes to arrive. This value will cause the API to timeout after the number of seconds configured if it has not been able to receive the data. The value is in seconds 0 indicates wait indefinitely | 0 | 2019.3 |
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.
| Setting | Purpose | Values |
|---|---|---|
| ApiTracing | Low level logging, calls, URL's payload sizes, response times and management events | 0 = Off, 1 = On |
| ApiLogging | High level, simply track start/stop of API services/threads | 0 = Off, 1 = On |
Starting as its own service
...
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).
...
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.
| Modifier | Definition | Example | Available |
|---|---|---|---|
| action | attachment | action=attachment | |
name | Name of the attachment in Greentree to replace (note do not use this when uploading a new attachment) | name=JobApplication | |
type | The Attachment Type in Greentree | type=Applications | |
| replaceIfExists | If NOT passing the name modifier, you can replace an existing attachment for the entity if it does exist based on the name embedded in the payload. Due to the expense of uploading files this is provided as a convenience method to avoid uploading the file only to find it already exists or that an update doesn't exist - you can use this to do it in a single call. | replaceIfExists=true | |
| modifiedSince | When requesting an attachment by name, you can also request to download the attachment ONLY if it has been modified since this specific date/time | modifiedSince=2014-06-21T23:34:00 | |
| summary | The summary to be used for the attachment | summary=A lovely photo taken yesterday | |
| isPrimary | Indicate that this attachment should be the Primary attachment for its Attachment Type. | isPrimary=true | 2021.1 |
| isWebAccessible | Indicate that this attachment should be set to Web Accessible | isWebAccessible=true | 2021.1 |
Sticky Notes
In Greentree sticky notes can be added to any object, as a result the API provides the ability to :
...
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:
| Modifier | Definition | Example |
|---|---|---|
| includeStickyNotes | Output the collection of Sticky Notes with each Greentree entity | includeStickyNotes=true |
stickyNoteType | Only include Sticky Notes of a particular type in the output. | stickyNoteType=DN |
Note that neither confidential nor inactive notes are able to be retrieved via the API.
...
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)
...
Plugin Property Modifiers:
| Modifier | Definition | Example |
|---|---|---|
| includePluginProperties | Output the Plugin Properties with each Greentree entity | includePluginProperties=true |
Sorting GET requests
(Available 2021 as preview)
...
The sort parameters can be combined with all the existing modifiers.
Sorting modifiers:
| Modifier | Definition | Example |
|---|---|---|
| sortBy<n> | Where n is an integer starting from 1, defines the name of the property to sort by | sortBy1=orderNumber |
| sortDesc<n> | Where n is an integer starting from 1, defines true if require to sort the matching property in descending order. This parameter is option, and the default sort order is ascending if not specified. | sortDesc1=true |
You can include any number of sort parameters, and you can also sort by reference properties.
...
- Sort AR Invoices by Branch, then by Document Date in descending order
Linked Objects
(Available 2020)
...
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:
| Modifier | Definition | Example |
|---|---|---|
| includeLinkedObjects | Output the Linked Objects with each Greentree entity | includeLinkedObjects=true |
Approvals
In Greentree approvals can be added to any object, as a result the API provides the ability to :
...
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 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:
| Attribute | Values | Notes |
|---|---|---|
| ReplaceIfExists | true / false | If there is already an attachment with the same name against the Object, determines if it will replace it or not |
| RespondWithAttachment | true/false | You can elect to run the report and attach it to the Object, but not require the PDF to be returned to you |
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.
...