AppBuilder API

An AppBuilder service - the api endpoint for our AppBuilder Runtime.

Install

See ab_cli

Pull Requests

Pull Requests should be tagged with a label major, minor or patch. Use major for breaking changes, minor for new features, or patch for bug fixes. To merge without creating a release a no_release tag can be added instead.

📝 In the pull request body add release notes between these tags:

<!-- #release_notes -->

<!-- /release_notes --> 

Anything between those 2 lines will be used as release notes when creating a version.

When merged:

• A new version will be created using semantic versioning
• The version will be updated in package.json
• A new tag and release will be created on GitHub
• A new docker image will be built, tagged with the version and published to dockerhub
• A Workflow in ab_runtime will be triggered to update the service version file.

Manually Building a Docker Image

It may be useful to build a custom docker image from a feature branch for testing. This can be done through a workflow dispatch trigger.

1. Go to the Actions tab
2. Select the 'Docker Build Custom' workflow
3. Select 'run Workflow' and fill in the form The image will be built from the selected branch and pushed to dockerhub using the given tags

---

Reference

• AppBuilder
  • CSV Export
  • Model Count
  • Model Create
  • Model Create Batch
  • Model Delete
  • Model Find
  • Model Update
  • Model Update Batch
• Auth
  • Login
  • Login Start
  • Logout
  • Okta Callback
  • Okta Error
  • Reset Password
  • Reset Verification
  • Set Password
  • Switcheroo
  • Switcheroo Clear
  • Who Am I
• Definition
  • All Applications
  • Check
  • Create
  • Delete
  • Export All
  • Export App
  • Import
  • Register
  • Update
  • Update App accross Tenant
  • User Applications
• File
  • Get a File
  • Get a File as base64
  • Upload
  • Upload a Base64 Encoded File
• Log
  • Find
• Mobile
  • App
  • Favicon
  • Manifest
  • QR
  • Version
• Multilingual
  • Missing Label
• Process
  • External Done
  • Inbox Find
  • Inbox Metadata
  • Inbox Register
  • Inbox Update
  • Task Reset
  • Timer Start
  • Timer Status
  • Timer Stop
• Relay
  • QR Code
• Report
  • View
  • Well Invoice
  • Well Receipt
• Tenant
  • Add
• Test
  • Import
  • Reset

---

AppBuilder

CSV Export - GET /appbuilder/csv-export/:viewID

Back to top

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
viewID	string	route
where	string	query	optional

Model Count - GET /app_builder/model/:objID/count

Back to top

Perform a Count operation on the data managed by a specified ABObject. This returns a count of all the matching rows specified by the {where} parameter.

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
objID	string	route	uuid of the ABObject
where	object	query	filter conditions to apply before counting

Responses

Success response - 200

Name	Type	Description
data	object
data.count	number	count of all the matching rows
status	string	"success"

Model Create - POST /app_builder/model/:objID

Back to top

Perform a Create operation on the data managed by a specified ABObject. This returns a fully populated row value of the newly created entry.

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
objID	string	route	uuid of the ABObject

Responses

Success response - 200

Name	Type	Description
data	object	populated row value of the newly created entry
status	string	"success"

Model Create Batch - POST /app_builder/model/:objID/batch

Back to top

Perform a Create operation on a batch of data managed by a specified ABObject. This returns a fully populated row value of the newly created entry.

NOTE: the incoming data contains an .id value used on the client to identify the entry. This is not part of the data being stored, but a local reference. Our return data references this .id to update the client with the results for that entry.

Parameters

Name	Type	Location	Description
objID	string	route	uuid of the ABObject to add to
batch	array	body	records to add

Responses

Success response - 200

Name	Type	Description
data	object
data.data	object	entries that added successfully { id: rowEntry }
data.errors	object	entries that could not be saved { id: error }
status	string	"success"

Model Delete - DELETE /app_builder/model/:objID/:ID

Back to top

Perform a Delete operation on the data managed by a specified ABObject.

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
objID	string	route	The uuid of the ABObject that the record to delete belongs to
ID	string	route	The uuid of the record to delete

Responses

Success response - 200

Name	Type	Description
data	object
data.numRows	number	The # of rows effected by our delete operation
status	string	"success"

Model Find - GET /app_builder/model/:objID

Back to top

Perform a Find operation on the data managed by a specified ABObject.

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
objID	string	route	The uuid of the ABObject
where	object	query	optional filter conditions
sort	array	query	optional specify the fields used for sorting [ { key: field.id, dir:["ASC", "DESC"]}, ... ]
populate	boolean|array	query	optional return values with their connections populated?
offset	number	query	optional the number of entries to skip.
limit	number	query	optional the number of return.

Responses

Success response - 200

Name	Type	Description
data	object
data.data	array	all the matching rows
data.total_count	number	count of the returned rows (for pagination)
data.pos	number	starting position (for pagination)
data.offset	number
data.limit	number
status	string	"success"

Model Update - PUT /app_builder/model/:objID/:id

Back to top

Perform an Update operation on the data managed by a specified ABObject. This returns a fully populated row value of the newly created entry.

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
ID	string	route	uuid of the record
objID	string	route	uuid of the ABObject
...params	any	body	any values to update, based on the ABObject's columns

Responses

Success response - 200

Name	Type	Description
data	object	row value
status	string	"success"

Model Update Batch - PUT /app_builder/batch/model/:objID

Back to top

Perform an Update operation on a batch of data managed by a specified ABObject.

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
objID	string	route	uuid of the ABObject
rowIds	string[]	body	uuids of the records to update
values	object	body	values to update

Responses

Success response - 200

Name	Type	Description
status	string	"success"
data	boolean	true

Auth

Login - POST /auth/login

Back to top

Process the provided login email/password and establish a user session if valid.

Permission: None

Parameters

Name	Type	Location	Description
email	string	body	user email
password	string	body	user password
tenant	string	body	optional tenant key

Responses

Success response - 200

Name	Type	Description
data	object
data.user	object
status	string	"success"

Login Start - GET /auth/login

Back to top

Start the login workflow based on the tenant's stategy

Permission: None

Logout - POST /auth/logout

Back to top

Clears the session and redirects the user

Permission: None

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Success response - 200 CAS

Name	Type	Description
data	object
data.redirect	string	if using CAS Authentication we send the redirect url for logout
status	string	"success"

Okta Callback - GET /authorization-code/callback

Back to top

This is an Okta callback route to finalize sign on

Permission: None

Responses

Success response - 302

Name	Type	Description
redirect		to /

Okta Error - GET /okta-error

Back to top

Handle an error response from Okta auth

Permission: None

Error response

Error response - 403

Name	Type	Description
Forbidden

Reset Password - POST /auth/login/reset

Back to top

Request an email to be sent to the user's address with a link to reset their password.

Permission: None

Parameters

Name	Type	Location	Description
url	string	body
email	string	body	user email
tenant	string	body	optional tenant key

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Reset Verification - POST /auth/password/reset

Back to top

Authenticate the user with tokens and redirect to the reset password page, used in the reset password emails

Permission: None

Parameters

Name	Type	Location	Description
t	string	query	tenant ID
a	string	query	auth token

Responses

Success response - 302

Name	Type	Description
redirect		redirect to login page

Set Password - POST /auth/password/reset

Back to top

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
password	string	body	user password

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Switcheroo - POST /auth/switcheroo/:userID

Back to top

Validate a request to switcheroo to another user.

Permission: Switcheroo - A user with the Switcheroo role

Parameters

Name	Type	Location	Description
userID	string	route	user to switch to

Responses

Success response - 200

Name	Type	Description
data	object
data.switcherooID	string	user switched to
status	string	"success"

Switcheroo Clear - DELETE /auth/switcheroo

Back to top

Remove a switcheroo assignment.

Permission: None

Responses

Success response - 200

Name	Type	Description
data	object
data.success	boolean	true
status	string	"success"

Who Am I - GET /auth/whoami

Back to top

Provide a simple { user:{username} } response if the user is logged in.

Permission: None

Responses

Success response - 200

Name	Type	Description
data	object
data.user	object
status	string	"success"

Definition

All Applications - GET /definition/allapplications

Back to top

Permission: Builder - A user with either the Builder or System Builder role

Responses

Success response - 200

Name	Type	Description
definitions	json

Check - GET /definition/check-update

Back to top

Check when the server last updated definitions. Used for cache busting /definition/myapps

Permission: none

Responses

Success response - 200

Name	Type	Description
data	number	the result of Date.now() when definitions were updated
status	string	"success"

Create - POST /definition/create

Back to top

Permission: Builder - A user with either the Builder or System Builder role

Parameters

Name	Type	Location	Description
id	string	body	a uuid
name	string	body
type	string	body
json	string	body

Responses

Success response - 200

Name	Type	Description
data	object	complete definition
status	string	"success"

Delete - DELETE /definition/:ID

Back to top

Permission: Builder - A user with either the Builder or System Builder role

Parameters

Name	Type	Location	Description
ID	string	route	uuid of the definition

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Export All - GET /definition/export/all

Back to top

Permission: Builder - A user with either the Builder or System Builder role

Parameters

Name	Type	Location	Description
download	number|boolean	query	optional whether to return the export as a file download

Responses

Success response - 200

Name	Type	Description
definitions	json

Export App - GET /definition/export/:ID

Back to top

Permission: Builder - A user with either the Builder or System Builder role

Parameters

Name	Type	Location	Description
ID	string	route	uuid of the ABApplication
download	number|boolean	query	optional whether to return the export as a file download

Responses

Success response - 200

Name	Type	Description
definitions	json

Import - POST /definition/import

Back to top

Import definitions from an uploaded json file

Permission: Builder - A user with either the Builder or System Builder role

Responses

Success response - 200

Name	Type	Description
status	string	"success"
data	object
data.done	boolean	true

Register - POST /definition/register

Back to top

Register for socket updates when definitons change

Permission: Builder - A user with either the Builder or System Builder role

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Update - PUT /definition/:id

Back to top

Permission: Builder - A user with either the Builder or System Builder role

Parameters

Name	Type	Location	Description
ID	string	route	uuid of the definition
...params	any	body	any values to update in the definition

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Update App accross Tenant - POST /definition/tenants-update-application

Back to top

Permission: Builder - A user with either the Builder or System Builder role

Parameters

Name	Type	Location	Description
applicationUUID	string	body
state	number	body	States { 0: create the file, 1: tranfer data of those keys, 2: done } Allowed values: 0,1,2
date	date	body
data	string	body	optional

Responses

Success response - 200

Name	Type	Description
status	string	"success"

User Applications - GET /definition/myapps

Back to top

Permission: none

Responses

Success response - 200

Name	Type	Description
definitions	text/javascript	script to add the app defintions

File

Get a File - GET /file/:ID

Back to top

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
ID	string	route	file uuid

Responses

Success response - 302

Name	Type	Description
url	redirect	to the file

Get a File as base64 - GET /file/:ID/base64

Back to top

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
ID	string	route	file uuid
mobile	boolean	query	whether to reutrn downscaled images for mobile

Responses

Success response - 200

Name	Type	Description
data	Object
data.image	string	base64
status	string	"success"

Upload - POST /file/upload/:objID/:fieldID

Back to top

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
fieldID	string	route
objID	string	route	uuid of the ABObject
isWebix	string	query	optional
file_fullpath	string	query	optional

Responses

Success response - 200

Name	Type	Description
data	Object
data.uuid	string
data.status	string	"server" if using a webix uploader
status	string	"success"

Upload a Base64 Encoded File - POST /file/upload/base64/:objID/:fieldID

Back to top

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
objID	uuid	route
fieldID	uuid	route
file	string	body
fileID	uuid	body
fileName	string	body
type	string	body
uploadedBy	string	body

Responses

Success response - 200

Name	Type	Description
data	Object
data.uuid	string
status	string	"success"

Log

Find - GET /app_builder/object/:objID/track

Back to top

Request a series of log entries for the data managed by a specific ABObject.

Permission: Builder - A user with either the Builder or System Builder role

Parameters

Name	Type	Location	Description
objID	string	route	uuid of the ABObject
rowId	string	query	optional The specific {row} entry we are looking for
levelName	string	query	optional the type of entries Allowed values: insert,update,delete
username	string	query	optional entries by a specific username
startDate	date	query	optional entries between a specific time frame
endDate	date	query	optional entries between a specific time frame
start	number	query	optional paging option
limit	number	query	optional paging option

Responses

Success response - 200

Name	Type	Description
data	object[]	log enteries
status	string	"success"

Mobile

App - GET /mobile/app/:appID

Back to top

Respond with the index.html of the Mobile PWA

Permission: None

Parameters

Name	Type	Location	Description
appID	string	route

Responses

Success response - 200

Name	Type	Description
html	HTML

Favicon - GET /mobile/app/:ID/favicon.png

Back to top

Respond with the favicon.png of the Mobile PWA

Permission: None

Responses

Success response - 301

Name	Type	Description
redirects	Redirect	to the tenant favicon.ico

Manifest - GET /mobile/app/:tenantID/:ID/manifest.json

Back to top

Respond with the manifest.json of the Mobile PWA

Permission: None

Responses

Success response - 200

Name	Type	Description
html	HTML

QR - GET /mobile/qr/:ID

Back to top

Respond with the QR code image for a specified app

Permission: None

Responses

Success response - 200

Name	Type	Description
html	HTML

Version - GET /mobile/version/:ID

Back to top

Respond with the current version # of the provided mobile app

Permission: None

Responses

Success response - 200

Name	Type	Description
data	object
data.version	object
status	string	"success"

Multilingual

Missing Label - POST /multilingual/label-missing

Back to top

report a missing label to add to the translations

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
labels	string	body	JSON string that parses to an array of objects with keys, key and altText

Parameters examples

json - Labels

{ "labels": "[{\"key\":\"example\", \"altText\": \"example\"}]" }

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Process

External Done - POST /process/external

Back to top

Allows an external approval task to report the task as done to continue the process.

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
task	object	body
task.id	string	body	id of the external approval task instance
data	object	body	optional any data to add to the process context

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Inbox Find - GET /process/inbox/

Back to top

Get the inbox tasks for the current user

Permission: User - Any authenticated user

Responses

Success response - 200

Name	Type	Description
data	Object[]	process tasks
status	string	"success"

Inbox Metadata - POST /process/inbox/meta

Back to top

Given a list of process ids, return a consolidated list of application-processes necessary for the UI to create the Inbox accordion

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
ids	string[]	body	process ids

Responses

Success response - 200

Name	Type	Description
data	Object[]	application and process metadata see example
status	string	"success"

Success response example

Success response example - 200

[{
  "id": "cbf95e19-805b-4793-8d27-56c0c8c9449e",
  "translations": [{
    "language_code": "en"
    "label": "Site Administration",
    "description": "Manage access to the web site for our users"
  }],
  "processes": [
    {
       "id": "24cb6b33-3ac5-432b-a4ad-c9ae7f12367a",
       "translations": [{
         "language_code": "en",
         "label": "approve new Role"
       }]
    }
  ]
}]

Inbox Register - POST /process/inbox/register

Back to top

Register for socket updates for realtime inbox updates

Permission: User - Any authenticated user

Responses

Success response - 200

Name	Type	Description
data	string	"ready" or "sockets not enabled, so no real time updates."
status	string	"success"

Inbox Update - PUT /process/inbox/:ID

Back to top

Complete an proces task from the inbox

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
ID	string	route	id of the inbox task
response	string	body	response to send to the process

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Task Reset - PUT /process/reset/:taskID

Back to top

send a signal to reset a specific process & task. This will cause that task to restart and run again.

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
taskID	string	route	uuid of the process task
instanceID	string/string[]	body	ids of process instances

Responses

Success response - 200

Name	Type	Description
data	number	the number of process resets
status	string	"success"

Timer Start - PUT /process/timer/:ID/start

Back to top

Permission: Builder - A user with either the Builder or System Builder role

Parameters

Name	Type	Location	Description
ID	string	route	uuid of a trigger timer

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Timer Status - GET /process/timer/:ID

Back to top

Permission: Builder - A user with either the Builder or System Builder role

Parameters

Name	Type	Location	Description
ID	string	route	uuid of a trigger timer

Responses

Success response - 200

Name	Type	Description
data	object
data.isRunning	boolean
status	string	"success"

Timer Stop - PUT /process/timer/:ID/stop

Back to top

Permission: Builder - A user with either the Builder or System Builder role

Parameters

Name	Type	Location	Description
ID	string	route	uuid of a trigger timer

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Relay

QR Code - GET /relay/user-qr

Back to top

Get a QR code to register the PWA

Permission: User - Any authenticated user

Responses

Success response - 200

Name	Type	Description
image	image/png	QR Code

Report

View - GET /report/:key

Back to top

Get a custom report

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
key	string	route	report to request
params...	any	query	additional params as required by the report

Responses

Success response - 200

Name	Type	Description
content	text/html	the html report

Well Invoice - GET /custom_reports/well-invoice

Back to top

Depreciated use /report/well-invoice

Well Receipt - GET /custom_reports/well-receipt

Back to top

Depreciated use /report/well-receipt

Tenant

Add - POST /tenant/add

Back to top

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
key	string	body	Short identifier for the tenant (no spaces)
title	string	body	Full Tenant name
authType	string	body	Authentication method to use for the tenant's users Allowed values: "login","okta","cas"
username	string	body	Username for the new tenant's admin user (will be created)
password	string	body	Password for the new admin user
email	string	body	Email of the new admin user
url	string	body	The tenants domain, must be a valid uri

Responses

Success response - 200

Name	Type	Description
status	string	"success"

Test

These routes are only available when running in test mode.

Import - POST /test/import

Back to top

Import definitions from a file already on the server.

Permission: User - Any authenticated user

Parameters

Name	Type	Location	Description
file	string	body	path to the file on the server

Responses

Success response - 200

Name	Type	Description
status	string	"success"
data	object
data.done	boolean	true

Reset - POST /test/reset

Back to top

Broadcast to other services that they need to update definitions. Useful when we've made a change in the DB directly.

Permission: None

Parameters

Name	Type	Location	Description
tenant	string	body	tenant key

Responses

Success response - 200

Name	Type	Description
status	string	"success"
data	object
data.done	boolean	true