Getting Started

Asset Essentials API URL

All Asset Essentials API URLs can be constructed by appending /api onto the end of your normal web application URL and then the endpoint.

 

https://assetessentials.dudesolutions.com/CompanyNameABC/api/v2/workorders

Rate Limiting

While there are currently no rate limits imposed by the Asset Essentials API, Brightly may impose limitations in the future as the need arises.

Response Results

All request data must be in JSON notation and all responses are returned the same way.

Response Pagination

All response data is paginated, and it is up to you to determine how your application will handle pagination and page requests. Most endpoints will return pagination data at the end of the response that indicate key pagination data. Asset Essentials uses PageNumber & PageSize as parameter values that can be overridden as needed.

Copy
"HasNextPage": true,
"HasPreviousPage": true,
"PageIndex": 0,
"TotalItems": 80,
"TotalPages": 4,
"PageNumber": 2,
"PageSize": 20

 

PageSize defaults to 10, but you can override this as a parameter. You will also need to specify a page number to move through the pages of data.

 

Copy
{{AE_URL}}/workorders?PageSize=20&PageNumber=2

 

You can determine your relative location in the available pages by utilizing the HasNextPage and HasPreviousPage values. When either value is false then you know you are on the first or last page depending on the field.

 

Setting the PageSize value to a large number in order to avoid pagination in the response data is discouraged as it will slow down your data retrieval and may cause timeouts to the API.

 

Authentication and Authorization

Asset Essentials uses a username and password for authentication and a token system for request authorization. When you authenticate with your credentials in the body of your login request, you will be returned a token to use with all subsequent requests to the API endpoints.

Copy

/login endpoint HTTP sample request:

POST /login HTTP/1.1
Host: {{AE_URL}}
Content-Type: application/x-www-form-urlencoded

 

In response you will receive a token in the response body. This token will be required as an Authorization header in all subsequent API requests. The provided token will remain valid for the Expires=120 period you had specified in the Authentication request to the /login endpoint. Time is in minutes.

Copy
Response Token
GET /workorders? HTTP/1.1
Host: {{AE_URL}}
Authorization: Basic {{AE_TOKEN}}
Content-Type: application/json

 

Error Responses

The most common error is 400 Bad Request due to a malformed request. The response body will return the cause of the error so that you can easily identify the problem and resolve it.

 

In this example a STRING character was sent instead of an INT which caused the request to be invalid, which is indicated in the response body.

Request

Copy
GET {{AE_URL}}/workorders/w

 

Response

Copy
{
    "Message": "The request is invalid.",
    "ModelState": {
        "id": [
            "The value 'w' is not valid for Int64."
        ]
    }
}

 

Time Zone Handling

The time zone of the API user account will be used in the body of the request when performing any date-related POST or PUT requests to some of the endpoints such as /workorders. This means that, for example, updating a DateCompleted value will need to take the account's time zone offset into account. It is recommended that your API user account be set to UTC so that you have a consistent offset to all of your API requests and responses and endpoints. Dates are stored as UTC so times will be correct when using the Asset Essentials GUI interface and it translates the time into local user time.

 

Commonly Used Endpoints

While there are many endpoints that can be accessed in Asset Essentials, most clients tend to use the following:

 

Endpoint Supported Method(s) Description
/login POST Pass credentials and get an Authentication Token in response
/workorders GET, POST, PUT, DELETE v1 endpoint for legacy integrations
/v2/workorders POST, PUT, DELETE v2 endpoint, use /searches or /quicksearches for bulk requests. No GET for bulk requests
/v2/workorders/searches POST Offers complex search filtering with bulk responses
/v2/workorders/quicksearches POST Offers complex search filtering with bulk responses but limited return data for efficiency
/assets GET, POST, PUT, DELETE endpoint to work with Asset data
/v2/meterreadings GET, POST, DELETE endpoint to work with meter readings on assets
/parts GET, POST, PUT, DELETE endpoint to work with parts
/purchaseorders GET, POST, PUT endpoint to work wit purchase orders

 

It is recommended that your first step is to perform a GET request on the endpoints you need to use in order to get a list of field names and their corresponding values that you can then compare to the Asset Essentials UI. Some of the field names in the API are different from the application UI and the JSON output will be invaluable in determining which field names you need to use.

 

Bulk vs Individual GET requests

Most endpoints allow you to make a bulk request to return all objects or with an ID to return a single object. The format for bulk requests is /endpoint where individual objects is /endpoint/ID.

Updating Objects (PUT method)

When updating an object using the PUT method you have two options for how you update the associated fields:

 

Both options are related to the fields that are received (FieldsUpdate) in response data and sent (FieldsToUpdate) with a request.

 

The FieldsUpdate values are a list of the fields of an object that can be updated, while the FieldsToUpdate values are an explicit list of fields that you want to update. By default if the FieldsToUpdate field is not sent, its value is assumed to be NULL and option 2 is enforced.

 

WorkOrder FieldsUpdate sample

Copy
"FieldsUpdate": [
    "Name",
    "WorkOrderNo",
    "WOStatusId",
    "WOTypeId",
    "WorkCategoryId",
    "WorkTypeId",
    "PriorityId",
],

 

Option 1: Include the FieldsToUpdate Key:value pair with an array of values

When an array of values is included with the FieldsToUpdate key, the API uses this list to limit updates to the specified fields. It is assumed that any field names not included in this array will not be subject to updates even if they are included in the request body. The syntax for the FieldsToUpdate field follows normal JSON array notation.

Copy
{
        "Description": "Electrical panel will not lock",
        "Note": "Panel J21 - key spins and does not turn the locking mechanism",
        "WOStatusId": 1,
        "FieldsToUpdate": ["Description", "Note"]
    }

 

Option 2: Do not include the FieldsToUpdate Key:Value pair or send with a NULL value

When no FieldsToUpdate values are sent in a request, all fields are assumed to be updated. If a field's Key:Value pair is not returned, or that value is empty, the original value will be replaced with a empty value. In this case you must capture and/or store all field values either upon object creation, or prior to an update request, and send those values back along with the altered Key:Value pair. Failure to send back existing field values will result in the loss of object data.

 

Filtering Work Order response data using Created and Modified dates

Created and Modified dates can be used with the /workorder endpoint as parameters to filter the response data.

Copy
Created Date - GET {{AE_URL}}/workorders/?utcDateCreatedStart=2010-03-28T23:47:00&utcDateCreatedEnd=2020-03-28T23:47:00
Modified Date - GET {{AE_URL}}/workorders/?utcDateModifiedStart=2010-03-28T23:47:00&utcDateModifiedEnd=2020-03-28T23:47:00

 

You can use both of the date range parameters at the same time if needed.

Copy
GET {{AE_URL}}/workorders/?utcDateCreatedStart=2010-03-28T23:47:00&utcDateCreatedEnd=2020-03-28T23:47:00&utcDateModifiedStart=2010-03-28T23:47:00&utcDateModifiedEnd=2020-03-28T23:47:00

 

Knowing the difference between object IDs and object Numbers (NO)

Most objects contain both an ID and a NO(number) and it is important to know the difference between the two when interacting with the API. The ID is the back end identifier for an object where the NO is an arbitrary label that can be used to customize aspects of the object. When sending GET and PUT requests for specific objects you need to use the ID and not the NO as a parameter. For example, The WorkOrderId may be wildly different from the WorkOrderNumber depending on how Asset Essentials is configured.

Copy
GET {{AE_URL}}/workorders/10
    {
        "WorkOrderId": 10,
        "WorkOrderNo": "0000000009",
    }

 

This means that you can update a Work Order number to match an externals system and have that number visible to the Asset Essentials user for system parity, but you would need to maintain a record of the base WorkOrderId value for future reference.

 

Working with custom fields

Asset Essentials allows the extensive creation and use of custom fields which are particularly useful when exchanging data between multiple systems. Custom fields that are set up in the Asset Essentials UI are accessible and update-able through the API. Please note that custom fields are associated with a type (Work Orders, Assets, Users) and then may have further optional restrictions placed on them that govern how they appear and behave. For example, if you have a Work Order custom field with a Work Category of HVAC, the custom field will only show up on a Work Order with HVAC as its Work Category.

 

Custom Fields in response data

There is different default behavior regarding the return of custom field data depending on how you make a request.

  • If you request an object by ID ( /workOrders/{ID} ) that object's associated custom field(s) will be returned.

  • If you request a bulk return of all objects ( /workOrders ) the custom fields are not returned.

 

Overriding the default custom field return behavior

If you need the custom field data to be included in a bulk request, you can add an additional parameter to your request. The customFields=True parameter can be used on its own or by chaining with other parameters.

 

Endpoint Filters as Query Parameters

You can pass a variety of ?filter= parameters on the request URI when you want to limit your results in some way. For endpoints that do not have a dedicated /searches resource, you can use the filter parameter. These parameters can be Strings, Ints, Bools and DateTime. Strings need to be enclosed in single quotes, Int and Bool values do not need to be enclosed, and DateTime values need to be URL encoded due to the nature of their required format.

 

Filter Formatting Examples

Strings

/purchaseorders?filter=LastModifiedby='Tools User'

INT & BOOL

/purchaseorders?filter=POStatusId=9

DateTime*

LastModifiedOn>=%28%232021-03-11T00:00:00%23%29

Multiple filters in the URI**

?filter=POStatusId=9 AND LastModifiedOn>=%28%232021-03-11T00:00:00%23%29 AND LastModifiedby='Admin Admin'

* Note that you have to URL encode the DateTime because it requires the format to be (#2021-03-11T00:00:00#) but the endpoints will not accept these as non-encoded values and will throw an error.

** This example uses AND and >= to build out the combined filters.

 

Supported Operators for Filters

Equals

=

Does not Equal

!=

Greater than

>

Less than

<

Greater than and equal to

>=

Less than and equal to

<=

Is between

Between(#2021-03-11#, #2021-03-16#)

Is not between

Not [LastModifiedOn] Between(#2021-03-11#, #2021-03-16#)

Is NULL

Is Null

Is not NULL

Is not NULL

 

WorkOrder Searches Filter List

The following is a complete listing of the /WorkOrder/searches filters that are available for use.