Sample Results Data Exports

Export Sample Data

The following are instructions on how to search for sample reports and export the data to excel. (See this page for more details: Excel Add-In.)

Click the Sample Reports tile on the left side.
You should see a screen that has Search Criteria in a blue bar. Click the Right-arrow on the right-side of that bar.
Enter data in whichever fields are relevant to your search (bottle ID, asset ID, etc.).
Once that data is entered, click the blue Refresh button in the top-right corner of the screen.
The results will populate in the list.
You can then export this information to an excel spreadsheet. Select the pull-down menu next to the Refresh button and clicking Export.
You will be prompted to allow Comments, summary and the sample results. Check all boxes that apply to your search. Click Submit when the desired settings have been selected.
You will get a confirmation that an email has been sent. Check your email for the exported excel document.

Note: Do NOT check the box on the left before Exporting. This will only select the items on the current page. Since each page shows 500 results, this will cause a 500-item limit when exporting.

Push/Publish Sample Data

Sample results data can be sent to a specific email, webhook/API or FTP. Set up your User Profile to include Sample Data Subscriptions. Format options include XLXS, JSON or XML format, by either an Email, FTP, or WEBHOOK/API.

Pull Sample Data via Restful API

Configure a company’s system to retrieve sample results data via a RESTful API
User must have logged in to MLA prior to requesting Authentication Token on Postman. The username and password will be used to request the Authentication Token on the postman or API platform.

Users should work with their IT team to setup this feature.

Postman

Guidance on interacting with, discovering, and using available resources and endpoints in the API is located in the postman documentation section specific to each API. It is intended for developers to interface with MLA via the RESTful HTTPS API.

Postman collection - MLA API Collection.postman_collection.json

API-enabled environments

Production endpoint - https://api.ucld.us/env/prd

Acceptance endpoint - https://api.ucld.us/env/acc

The Acceptance environment is for testing, and access is limited. Please contact your local Exxon representative for access.

API

Authentication

Authentication endpoint is used to obtain an authentication token to be used with subsequent requests. There are two different types of parameters that can be used to obtain the token.

UserName and Password (preferred)

Username - Required. Email address of the Mobil Lubricant Analysis user to be authenticated as.

Password - Required. Mobil Lubricant Analysis password of the user authenticating.

APIkey and email or userid

To retrieve your user API key, please contact your local technical helpdesk.

Retrieving individual samples

The Get Completed Samples API is used to retrieve an individual sample’s full results. For instance, what a user would see from the LIMS Details page. Two variations on this API exist: Get Completed Samples by Workflow Report ID and Get Completed Samples by Bottle ID. Both these APIs are governed by the security right View Sample Details.

Get Completed Samples by Workflow Report ID

Endpoint: https://api.ucld.us/env/{{environment}}/sample/workflowreportid/:sampleworkflowreportid

The sample’s workflow report ID can be retrieved in several ways. The simplest through the UI is to use the ID in the sample report page’s URL. This can be retrieved through APIs by using Get Workflow Reports. Use it to filter on the sample results workflows (workflow ID 5031). Be sure to provide the ID of the specific results you would like to retrieve. Get Workflow Reports is described in more detail below.

Get Completed Samples by Bottle ID

Endpoint: https://api.ucld.us/env/{{environment}}/sample/bottleid/:bottleid

Like above, there are multiple ways to retrieve a sample’s bottle ID. Get Workflow Reports can also be used to retrieve the bottle ID from an individual sample.

Retrieving collections of samples

The Get Sample Activity API is used to retrieve collections of sample reports with high-level details. These include statuses without individual test results on the samples. Two main variations exist on this API: Get Sample Activity by Asset and Get Sample Activity by Account. The Get Sample Data API can fetch detailed samples and results, similar to the 'Sample Activity Results' export format.

Like the Sample Activity Report page, these APIs are governed by the security right View Sample Activity Report.

Get Sample Activity by Account

Endpoint: https://api.ucld.us/env/{{environment}}/sampleactivity/filter/accountid/:clientId

This API will return all sample results on all assets in a specified account. The client ID used in the above URL is a unique GUID associated with each account. In the UI, this can be retrieved from an account’s Account Details URL. Account APIs are described in more detail below.

Get Sample Activity by Asset

Endpoint: https://api.ucld.us/env/{{environment}}/sampleactivity/filter/assetid/:assetid

This API will return all sample results on a specified asset. The asset ID used in the above URL is referred to as asset key on the Asset Details page. When retrieved through asset APIs, It’s UCAssetId. Some asset APIs are described below in more detail.

Get Sample Data

Endpoint: https://api.ucld.us/env/{{environment}}/samplereport/getsampledata

This API lets users fetch samples for specific assets or accounts within a date range. Additional filtering by sample status and asset class is also available. At least one asset or account is required to return results.

Each set of filter criteria can be entered as an array and have multiple criteria. For account, the account name is entered as criteria. For asset, the asset ID (not UCAssetID) is entered as criteria. For sample status, the plain text of that status is entered as the criteria. For asset class, the asset class’s name is entered as the criteria. You can additionally filter by lubricant’s name. Unlike the above criteria, only one lubricant can be filtered on at a time. Workflow data and sample comments can also be optionally turned on and off.

Additional APIs

The below APIs can be used in conjunction with the various sample APIs above.

Get Accounts

Endpoint: https://api.ucld.us/env/{{environment}}/account/getaccounts/?searchterm=

The Get Accounts API can be used to search for a specific account or return all your accounts. Like the Account Search and Account Details page, this API is governed by the security right View Accounts.

Get My Accounts

Endpoint: https://api.ucld.us/env/{{environment}}/account/getaccounts

The Get My Accounts API retrieves all your user’s assigned accounts. This is also governed by the security right View Accounts.

Get Assets

Endpoint: https://api.ucld.us/env/{{environment}}/asset/getassets

The Get Assets API can be used to search for specific assets. The 'ClientID' field can be filled with the Client ID of any account returned from the above account APIs. Alternatively, enter 'MY_CLIENTS' to include all assets in your assigned accounts. Additional filter options are available. They can be added to SearchFacets and are retrieved using the Get Basic Search Facets API below. Like the Asset Search page, the Get Assets API is governed by the View Assets security right.

Get Basic Search Facets

Endpoint: https://api.ucld.us/env/{{environment}}/asset/basicfilters

This API simply retrieves all facets that can be used in the Get Assets API above. This API is not governed by any security rights and is available to any authenticated user.

Get Workflow Reports

Endpoint: http://{{environment}}.ucld.us/getwfreports.ashxsr=0&k=&c=&ac=&wf=5031&a=&wfr=&s=&e=

The Get Workflow Reports API is a very flexible API used to retrieve workflow reports generally. It can also be used to search of completed sample reports as well. This is done by specifying the Sample Results workflow (workflow ID 5031) in the workflow parameter in the URL. Additional filters can be added for account, asset class, individual assets, and start and end dates.

This API does not require any specific security right. It requires a user to be authenticated or pass their user’s API key in the parameters. Users will only be able to access data for assets they would normally have access to, however.