mirror of
https://github.com/Kingsrook/qqq.git
synced 2025-07-21 14:38:43 +00:00
1953 lines
80 KiB
YAML
1953 lines
80 KiB
YAML
components:
|
|
schemas:
|
|
AppMetaData:
|
|
properties:
|
|
childMap:
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/AppTreeNode"
|
|
description: "Map of other apps, tables, process, and reports, which are\
|
|
\ contained within this app. Same contents as the children list, just\
|
|
\ structured as a map."
|
|
type: "object"
|
|
children:
|
|
description: "List of other apps, tables, process, and reports, which are\
|
|
\ contained within this app."
|
|
items:
|
|
$ref: "#/components/schemas/AppTreeNode"
|
|
type: "array"
|
|
icon:
|
|
$ref: "#/components/schemas/Icon"
|
|
description: "Icon to display for the app."
|
|
label:
|
|
description: "User-facing name for this app"
|
|
type: "string"
|
|
name:
|
|
description: "Unique name for this app within the QQQ Instance"
|
|
type: "string"
|
|
sections:
|
|
description: "List of sections - sub-divisions of the app, to further organize\
|
|
\ its children."
|
|
items:
|
|
$ref: "#/components/schemas/AppSection"
|
|
type: "array"
|
|
supplementalAppMetaData:
|
|
description: "Additional meta-data describing the app, which may not be\
|
|
\ known to the QQQ backend core module."
|
|
type: "object"
|
|
widgets:
|
|
description: "List of widgets names that are part of this app. These strings\
|
|
\ should be keys to the widgets map in the QQQ Instance."
|
|
items:
|
|
type: "string"
|
|
type: "array"
|
|
type: "object"
|
|
AppSection:
|
|
properties:
|
|
icon:
|
|
$ref: "#/components/schemas/Icon"
|
|
description: "Icon to display for the section."
|
|
label:
|
|
description: "User-facing name of the section."
|
|
type: "string"
|
|
name:
|
|
description: "Unique (within the app) name for this section."
|
|
type: "string"
|
|
processes:
|
|
description: "List of process names for the section"
|
|
items:
|
|
type: "string"
|
|
type: "array"
|
|
reports:
|
|
description: "List of report names for the section"
|
|
items:
|
|
type: "string"
|
|
type: "array"
|
|
tables:
|
|
description: "List of table names for the section"
|
|
items:
|
|
type: "string"
|
|
type: "array"
|
|
type: "object"
|
|
AppTreeNode:
|
|
properties:
|
|
children:
|
|
description: "Child elements. Only applies for type='app', which contains\
|
|
\ additional apps under it"
|
|
items:
|
|
$ref: "#/components/schemas/AppTreeNode"
|
|
type: "array"
|
|
icon:
|
|
$ref: "#/components/schemas/Icon"
|
|
description: "Icon to display for the item."
|
|
label:
|
|
description: "User-facing name of the element."
|
|
type: "string"
|
|
name:
|
|
description: "Unique (within its type) name for this element. e.g., for\
|
|
\ type = 'table', the table's name."
|
|
type: "string"
|
|
type:
|
|
description: "The type of node (table, process, report, app)"
|
|
type: "string"
|
|
type: "object"
|
|
AuthenticationMetaDataResponseV1:
|
|
properties:
|
|
name:
|
|
description: "Unique name for the authentication metaData object within\
|
|
\ the QInstance.\n"
|
|
type: "string"
|
|
type:
|
|
description: "Specifier for the type of authentication module being used.\n\
|
|
\nFrontends should use this value to determine how to prompt the user\
|
|
\ for authentication credentials.\nIn addition, depending on this value,\
|
|
\ additional properties will be included in this object, as\nmay be needed\
|
|
\ to complete the authorization workflow with the provider (e.g., a baseUrl,\
|
|
\ clientId,\nand audience for an OAuth type workflow)."
|
|
type: "string"
|
|
values:
|
|
description: "Additional values, as determined by the type of authentication\
|
|
\ provider.\n"
|
|
oneOf:
|
|
- description: "No additional values are used for some authentication providers."
|
|
type: "object"
|
|
- description: "Additional values used by the Auth0 type authentication\
|
|
\ provider."
|
|
properties:
|
|
audience:
|
|
description: "Audience for auth0"
|
|
type: "string"
|
|
baseUrl:
|
|
description: "BaseUrl for auth0"
|
|
type: "string"
|
|
clientId:
|
|
description: "ClientId for auth0"
|
|
type: "string"
|
|
type: "object"
|
|
type: "object"
|
|
BasicErrorResponseV1:
|
|
properties:
|
|
error:
|
|
description: "Description of the error"
|
|
type: "string"
|
|
type: "object"
|
|
FieldAdornment:
|
|
properties:
|
|
type:
|
|
description: "Type of this adornment"
|
|
enum:
|
|
- "LINK"
|
|
- "CHIP"
|
|
- "SIZE"
|
|
- "CODE_EDITOR"
|
|
- "RENDER_HTML"
|
|
- "REVEAL"
|
|
- "FILE_DOWNLOAD"
|
|
- "ERROR"
|
|
type: "string"
|
|
values:
|
|
description: "Values associated with this adornment. Keys and the meanings\
|
|
\ of their values will differ by type."
|
|
type: "object"
|
|
type: "object"
|
|
FieldMetaData:
|
|
properties:
|
|
adornments:
|
|
description: "Special UI dressings to add to the field."
|
|
items:
|
|
$ref: "#/components/schemas/FieldAdornment"
|
|
type: "array"
|
|
defaultValue:
|
|
description: "Default value to use in this field."
|
|
type: "string"
|
|
displayFormat:
|
|
description: "C-style format specifier for displaying values in this field."
|
|
type: "string"
|
|
isEditable:
|
|
description: "Indicate if user may edit the value in this field."
|
|
type: "boolean"
|
|
isHeavy:
|
|
description: "Indicator of 'heavy' fields, which are not loaded by default.\
|
|
\ e.g., some blobs or long-texts"
|
|
type: "boolean"
|
|
isHidden:
|
|
description: "Indicate if this field should be hidden from users"
|
|
type: "boolean"
|
|
isRequired:
|
|
description: "Indicate if a value in this field is required."
|
|
type: "boolean"
|
|
label:
|
|
description: "User-facing name for this field"
|
|
type: "string"
|
|
maxLength:
|
|
description: "For String fields, the max length the field supports."
|
|
type: "number"
|
|
name:
|
|
description: "Unique name for this field within its container (table or\
|
|
\ process)"
|
|
type: "string"
|
|
possibleValueSourceName:
|
|
description: "If this field's values should come from a possible value source,\
|
|
\ then that PVS is named here."
|
|
type: "string"
|
|
type:
|
|
description: "Data-type for this field"
|
|
type: "string"
|
|
type: "object"
|
|
FrontendComponent:
|
|
properties:
|
|
type:
|
|
description: "The type of this component. e.g., what kind of UI element(s)\
|
|
\ should be presented to the user."
|
|
enum:
|
|
- "HELP_TEXT"
|
|
- "BULK_EDIT_FORM"
|
|
- "VALIDATION_REVIEW_SCREEN"
|
|
- "EDIT_FORM"
|
|
- "VIEW_FORM"
|
|
- "DOWNLOAD_FORM"
|
|
- "RECORD_LIST"
|
|
- "PROCESS_SUMMARY_RESULTS"
|
|
- "GOOGLE_DRIVE_SELECT_FOLDER"
|
|
- "WIDGET"
|
|
- "HTML"
|
|
type: "string"
|
|
values:
|
|
$ref: "#/components/schemas/FrontendComponentValues"
|
|
description: "Name-value pairs specific to the type of component."
|
|
type: "object"
|
|
type: "object"
|
|
FrontendComponentValues:
|
|
additionalProperties: true
|
|
description: "These are the known values that can appear in the values map under\
|
|
\ a FrontendComponent, to control\nhow that component should be presented\
|
|
\ to the user.\n\nNote that additional properties may appear as well.\n\n\
|
|
In addition, components are expected to use values from an active process's\
|
|
\ `values` map (e.g., as included in\na `ProcessStepComplete` object), with\
|
|
\ the following contract between component-types and expected values:\n\n\
|
|
- For component type=`HTML`, there will be a process value with key=`${stepName}.html`\
|
|
\ (e.g., `resultScreen.html`),\nwhose value is the HTML to display on that\
|
|
\ screen.\n- For component type=`HELP_TEXT`: There will be a process value\
|
|
\ with key=`text`, whose value is the text to display on that screen.\nThere\
|
|
\ may also be a process value with key=`previewText`, which, if present, can\
|
|
\ be shown before the full text is shown,\ne.g., with a toggle control to\
|
|
\ hide/show the `text` value.\n"
|
|
properties:
|
|
blocks:
|
|
description: "Components of type=`WIDGET`, which are set as `isAdHocWidget=true`,\
|
|
\ should include a list of WidgetBlocks in this value."
|
|
items:
|
|
$ref: "#/components/schemas/WidgetBlock"
|
|
type: "array"
|
|
includeFieldNames:
|
|
description: "Components of type=`EDIT_FORM` can specify a subset of field\
|
|
\ names to include. This can be used to break a form up into\nsections,\
|
|
\ by including multiple EDIT_FORM components, with different lists of\
|
|
\ `includeFieldNames`.\n"
|
|
items:
|
|
type: "string"
|
|
type: "array"
|
|
isAdHocWidget:
|
|
description: "Components of type=`WIDGET`, which do not reference a widget\
|
|
\ defined in the QQQ Instance, but instead,\nare defined as a list of\
|
|
\ blocks within a frontend step component, will have a this value set\
|
|
\ to true."
|
|
type: "boolean"
|
|
sectionLabel:
|
|
description: "Components of type=`EDIT_FORM` can specify a user-facing text\
|
|
\ label to show on screen.\n"
|
|
type: "string"
|
|
widgetName:
|
|
description: "Components of type=`WIDGET`, which should render a widget\
|
|
\ defined in the QQQ instance, this value specifies\nthe name of that\
|
|
\ widget. Contrast with ad-hoc widgets.\n"
|
|
type: "string"
|
|
type: "object"
|
|
FrontendStep:
|
|
properties:
|
|
components:
|
|
description: "The components that make up this screen"
|
|
items:
|
|
$ref: "#/components/schemas/FrontendComponent"
|
|
type: "array"
|
|
formFields:
|
|
description: "Fields used as form fields (inputs) on this step/screen"
|
|
items:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
type: "array"
|
|
format:
|
|
description: "An optional indicator of the screen format preferred by the\
|
|
\ application to be used for this screen. Different frontends may support\
|
|
\ different formats, and implement them differently."
|
|
type: "string"
|
|
label:
|
|
description: "The user-facing name for this step"
|
|
type: "string"
|
|
name:
|
|
description: "The unique name for this step within its process"
|
|
type: "string"
|
|
recordListFields:
|
|
description: "Fields used in record-lists shown on the step/screen."
|
|
items:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
type: "array"
|
|
viewFields:
|
|
description: "Fields used as view-only fields on this step/screen"
|
|
items:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
type: "array"
|
|
type: "object"
|
|
Icon:
|
|
properties:
|
|
color:
|
|
description: "A color code to use for displaying the icon"
|
|
type: "string"
|
|
name:
|
|
description: "A material UI icon name."
|
|
type: "string"
|
|
path:
|
|
description: "A path to an image file that can be requested from the server,\
|
|
\ to serve as the icon image instead of a material UI icon."
|
|
type: "string"
|
|
type: "object"
|
|
ManageSessionResponseV1:
|
|
properties:
|
|
uuid:
|
|
description: "Unique identifier of the session. Required to be returned\
|
|
\ on subsequent requests in the sessionUUID Cookie, to prove authentication."
|
|
type: "string"
|
|
values:
|
|
additionalProperties: true
|
|
description: "Optional object with application-defined values."
|
|
type: "object"
|
|
type: "object"
|
|
MetaDataResponseV1:
|
|
properties:
|
|
appTree:
|
|
description: "Tree of apps within the QQQ Instance, sorted and organized\
|
|
\ hierarchically, for presentation to a user."
|
|
items:
|
|
$ref: "#/components/schemas/AppTreeNode"
|
|
type: "array"
|
|
apps:
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/AppMetaData"
|
|
description: "Map of all apps within the QQQ Instance (that the user has\
|
|
\ permission to see that they exist)."
|
|
type: "object"
|
|
processes:
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/ProcessMetaDataLight"
|
|
description: "Map of all processes within the QQQ Instance (that the user\
|
|
\ has permission to see that they exist)."
|
|
type: "object"
|
|
tables:
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/TableMetaDataLight"
|
|
description: "Map of all tables within the QQQ Instance (that the user has\
|
|
\ permission to see that they exist)."
|
|
type: "object"
|
|
widgets:
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/ProcessMetaDataLight"
|
|
description: "Map of all widgets within the QQQ Instance (that the user\
|
|
\ has permission to see that they exist)."
|
|
type: "object"
|
|
type: "object"
|
|
ProcessMetaData:
|
|
properties:
|
|
frontendSteps:
|
|
description: "Frontend steps (aka, Screens) for this process."
|
|
items:
|
|
$ref: "#/components/schemas/FrontendStep"
|
|
type: "array"
|
|
hasPermission:
|
|
description: "Boolean to indicate if the user has permission for the process."
|
|
type: "boolean"
|
|
icon:
|
|
$ref: "#/components/schemas/Icon"
|
|
description: "Icon to display for the process."
|
|
isHidden:
|
|
description: "Boolean indicator of whether the process should be shown to\
|
|
\ users or not"
|
|
type: "boolean"
|
|
label:
|
|
description: "User-facing name for this process"
|
|
type: "string"
|
|
name:
|
|
description: "Unique name for this process within the QQQ Instance"
|
|
type: "string"
|
|
stepFlow:
|
|
description: "Indicator of the Step Flow used by the process. Possible\
|
|
\ values are: LINEAR, STATE_MACHINE."
|
|
type: "string"
|
|
tableName:
|
|
description: "If this process is associated with a table, the table name\
|
|
\ is given here"
|
|
type: "string"
|
|
type: "object"
|
|
ProcessMetaDataAdjustment:
|
|
properties:
|
|
updatedFields:
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
description: "Fields whose meta-data has changed. e.g., changing a label,\
|
|
\ or required status, or inline-possible-values."
|
|
type: "object"
|
|
updatedFrontendStepList:
|
|
description: "In case the backend has changed the list of frontend steps,\
|
|
\ it will be set in this field."
|
|
items:
|
|
$ref: "#/components/schemas/FrontendStep"
|
|
type: "array"
|
|
type: "object"
|
|
ProcessMetaDataLight:
|
|
properties:
|
|
hasPermission:
|
|
description: "Boolean to indicate if the user has permission for the process."
|
|
type: "boolean"
|
|
icon:
|
|
$ref: "#/components/schemas/Icon"
|
|
description: "Icon to display for the process."
|
|
isHidden:
|
|
description: "Boolean indicator of whether the process should be shown to\
|
|
\ users or not"
|
|
type: "boolean"
|
|
label:
|
|
description: "User-facing name for this process"
|
|
type: "string"
|
|
name:
|
|
description: "Unique name for this process within the QQQ Instance"
|
|
type: "string"
|
|
stepFlow:
|
|
description: "Indicator of the Step Flow used by the process. Possible\
|
|
\ values are: LINEAR, STATE_MACHINE."
|
|
type: "string"
|
|
tableName:
|
|
description: "If this process is associated with a table, the table name\
|
|
\ is given here"
|
|
type: "string"
|
|
type: "object"
|
|
ProcessMetaDataResponseV1:
|
|
properties:
|
|
frontendSteps:
|
|
description: "Frontend steps (aka, Screens) for this process."
|
|
items:
|
|
$ref: "#/components/schemas/FrontendStep"
|
|
type: "array"
|
|
hasPermission:
|
|
description: "Boolean to indicate if the user has permission for the process."
|
|
type: "boolean"
|
|
icon:
|
|
description: "Icon to display for the process."
|
|
properties:
|
|
color:
|
|
description: "A color code to use for displaying the icon"
|
|
type: "string"
|
|
name:
|
|
description: "A material UI icon name."
|
|
type: "string"
|
|
path:
|
|
description: "A path to an image file that can be requested from the\
|
|
\ server, to serve as the icon image instead of a material UI icon."
|
|
type: "string"
|
|
type: "object"
|
|
isHidden:
|
|
description: "Boolean indicator of whether the process should be shown to\
|
|
\ users or not"
|
|
type: "boolean"
|
|
label:
|
|
description: "User-facing name for this process"
|
|
type: "string"
|
|
name:
|
|
description: "Unique name for this process within the QQQ Instance"
|
|
type: "string"
|
|
stepFlow:
|
|
description: "Indicator of the Step Flow used by the process. Possible\
|
|
\ values are: LINEAR, STATE_MACHINE."
|
|
type: "string"
|
|
tableName:
|
|
description: "If this process is associated with a table, the table name\
|
|
\ is given here"
|
|
type: "string"
|
|
type: "object"
|
|
ProcessStepComplete:
|
|
description: "Data returned after the job is complete (whether it was synchronous,\
|
|
\ or asynchronous)"
|
|
properties:
|
|
nextStep:
|
|
description: "Name of the next process step that needs to run (a frontend\
|
|
\ step). If there are no more steps in the process, this field will not\
|
|
\ be included. "
|
|
type: "string"
|
|
processMetaDataAdjustment:
|
|
description: "Changes to be made to the process's metaData."
|
|
properties:
|
|
updatedFields:
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
description: "Fields whose meta-data has changed. e.g., changing a\
|
|
\ label, or required status, or inline-possible-values."
|
|
type: "object"
|
|
updatedFrontendStepList:
|
|
description: "In case the backend has changed the list of frontend steps,\
|
|
\ it will be set in this field."
|
|
items:
|
|
properties:
|
|
components:
|
|
description: "The components that make up this screen"
|
|
items:
|
|
$ref: "#/components/schemas/FrontendComponent"
|
|
type: "array"
|
|
formFields:
|
|
description: "Fields used as form fields (inputs) on this step/screen"
|
|
items:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
type: "array"
|
|
format:
|
|
description: "An optional indicator of the screen format preferred\
|
|
\ by the application to be used for this screen. Different\
|
|
\ frontends may support different formats, and implement them\
|
|
\ differently."
|
|
type: "string"
|
|
label:
|
|
description: "The user-facing name for this step"
|
|
type: "string"
|
|
name:
|
|
description: "The unique name for this step within its process"
|
|
type: "string"
|
|
recordListFields:
|
|
description: "Fields used in record-lists shown on the step/screen."
|
|
items:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
type: "array"
|
|
viewFields:
|
|
description: "Fields used as view-only fields on this step/screen"
|
|
items:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
type: "array"
|
|
type: "object"
|
|
type: "array"
|
|
type: "object"
|
|
processUUID:
|
|
description: "Unique identifier for a running instance the process."
|
|
type: "string"
|
|
type:
|
|
description: "What kind of response has been received. Determines what\
|
|
\ additional fields will be set."
|
|
type: "string"
|
|
values:
|
|
description: "Current values for fields used by the process.Keys are Strings,\
|
|
\ values can be any type, as determined by the application & process."
|
|
type: "object"
|
|
type: "object"
|
|
ProcessStepError:
|
|
description: "In case an error is thrown in the backend job."
|
|
properties:
|
|
error:
|
|
description: "Exception message, in case the process step threw an error."
|
|
type: "string"
|
|
processUUID:
|
|
description: "Unique identifier for a running instance the process."
|
|
type: "string"
|
|
type:
|
|
description: "What kind of response has been received. Determines what\
|
|
\ additional fields will be set."
|
|
type: "string"
|
|
userFacingError:
|
|
description: "Optional user-facing exception message, in case the process\
|
|
\ step threw a user-facing error."
|
|
type: "string"
|
|
type: "object"
|
|
ProcessStepJobStarted:
|
|
description: "In case the backend needs more time, this is a UUID of the background\
|
|
\ job that has been started."
|
|
properties:
|
|
jobUUID:
|
|
description: "Unique identifier for a running step of the process. Must\
|
|
\ be passed into `status` check calls."
|
|
type: "string"
|
|
processUUID:
|
|
description: "Unique identifier for a running instance the process."
|
|
type: "string"
|
|
type:
|
|
description: "What kind of response has been received. Determines what\
|
|
\ additional fields will be set."
|
|
type: "string"
|
|
type: "object"
|
|
ProcessStepResponseV1:
|
|
oneOf:
|
|
- description: "Data returned after the job is complete (whether it was synchronous,\
|
|
\ or asynchronous)"
|
|
properties:
|
|
nextStep:
|
|
description: "Name of the next process step that needs to run (a frontend\
|
|
\ step). If there are no more steps in the process, this field will\
|
|
\ not be included. "
|
|
type: "string"
|
|
processMetaDataAdjustment:
|
|
description: "Changes to be made to the process's metaData."
|
|
properties:
|
|
updatedFields:
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
description: "Fields whose meta-data has changed. e.g., changing\
|
|
\ a label, or required status, or inline-possible-values."
|
|
type: "object"
|
|
updatedFrontendStepList:
|
|
description: "In case the backend has changed the list of frontend\
|
|
\ steps, it will be set in this field."
|
|
items:
|
|
properties:
|
|
components:
|
|
description: "The components that make up this screen"
|
|
items:
|
|
$ref: "#/components/schemas/FrontendComponent"
|
|
type: "array"
|
|
formFields:
|
|
description: "Fields used as form fields (inputs) on this step/screen"
|
|
items:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
type: "array"
|
|
format:
|
|
description: "An optional indicator of the screen format preferred\
|
|
\ by the application to be used for this screen. Different\
|
|
\ frontends may support different formats, and implement them\
|
|
\ differently."
|
|
type: "string"
|
|
label:
|
|
description: "The user-facing name for this step"
|
|
type: "string"
|
|
name:
|
|
description: "The unique name for this step within its process"
|
|
type: "string"
|
|
recordListFields:
|
|
description: "Fields used in record-lists shown on the step/screen."
|
|
items:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
type: "array"
|
|
viewFields:
|
|
description: "Fields used as view-only fields on this step/screen"
|
|
items:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
type: "array"
|
|
type: "object"
|
|
type: "array"
|
|
type: "object"
|
|
processUUID:
|
|
description: "Unique identifier for a running instance the process."
|
|
type: "string"
|
|
type:
|
|
description: "What kind of response has been received. Determines what\
|
|
\ additional fields will be set."
|
|
type: "string"
|
|
values:
|
|
description: "Current values for fields used by the process.Keys are Strings,\
|
|
\ values can be any type, as determined by the application & process."
|
|
type: "object"
|
|
type: "object"
|
|
- description: "In case the backend needs more time, this is a UUID of the background\
|
|
\ job that has been started."
|
|
properties:
|
|
jobUUID:
|
|
description: "Unique identifier for a running step of the process. Must\
|
|
\ be passed into `status` check calls."
|
|
type: "string"
|
|
processUUID:
|
|
description: "Unique identifier for a running instance the process."
|
|
type: "string"
|
|
type:
|
|
description: "What kind of response has been received. Determines what\
|
|
\ additional fields will be set."
|
|
type: "string"
|
|
type: "object"
|
|
- description: "Response to a status check for a backgrounded job."
|
|
properties:
|
|
current:
|
|
description: "Optional indicator of progress (e.g., `current` of `total`,\
|
|
\ as in (`1 of 10`)."
|
|
type: "number"
|
|
message:
|
|
description: "Status message regarding the running process step."
|
|
type: "string"
|
|
processUUID:
|
|
description: "Unique identifier for a running instance the process."
|
|
type: "string"
|
|
total:
|
|
description: "Optional indicator of progress (e.g., `current` of `total`,\
|
|
\ as in (`1 of 10`)."
|
|
type: "number"
|
|
type:
|
|
description: "What kind of response has been received. Determines what\
|
|
\ additional fields will be set."
|
|
type: "string"
|
|
type: "object"
|
|
- description: "In case an error is thrown in the backend job."
|
|
properties:
|
|
error:
|
|
description: "Exception message, in case the process step threw an error."
|
|
type: "string"
|
|
processUUID:
|
|
description: "Unique identifier for a running instance the process."
|
|
type: "string"
|
|
type:
|
|
description: "What kind of response has been received. Determines what\
|
|
\ additional fields will be set."
|
|
type: "string"
|
|
userFacingError:
|
|
description: "Optional user-facing exception message, in case the process\
|
|
\ step threw a user-facing error."
|
|
type: "string"
|
|
type: "object"
|
|
ProcessStepRunning:
|
|
description: "Response to a status check for a backgrounded job."
|
|
properties:
|
|
current:
|
|
description: "Optional indicator of progress (e.g., `current` of `total`,\
|
|
\ as in (`1 of 10`)."
|
|
type: "number"
|
|
message:
|
|
description: "Status message regarding the running process step."
|
|
type: "string"
|
|
processUUID:
|
|
description: "Unique identifier for a running instance the process."
|
|
type: "string"
|
|
total:
|
|
description: "Optional indicator of progress (e.g., `current` of `total`,\
|
|
\ as in (`1 of 10`)."
|
|
type: "number"
|
|
type:
|
|
description: "What kind of response has been received. Determines what\
|
|
\ additional fields will be set."
|
|
type: "string"
|
|
type: "object"
|
|
TableMetaDataLight:
|
|
properties:
|
|
capabilities:
|
|
description: "List of strings describing actions that are supported by the\
|
|
\ backend application for the table."
|
|
items:
|
|
type: "string"
|
|
type: "array"
|
|
deletePermission:
|
|
description: "Boolean to indicate if the user has delete permission for\
|
|
\ the table."
|
|
type: "boolean"
|
|
editPermission:
|
|
description: "Boolean to indicate if the user has edit permission for the\
|
|
\ table."
|
|
type: "boolean"
|
|
helpContents:
|
|
description: "Help Contents for this table."
|
|
type: "object"
|
|
icon:
|
|
$ref: "#/components/schemas/Icon"
|
|
description: "Icon to display for the table"
|
|
insertPermission:
|
|
description: "Boolean to indicate if the user has insert permission for\
|
|
\ the table."
|
|
type: "boolean"
|
|
isHidden:
|
|
description: "Boolean indicator of whether the table should be shown to\
|
|
\ users or not"
|
|
type: "boolean"
|
|
label:
|
|
description: "User-facing name for this table"
|
|
type: "string"
|
|
name:
|
|
description: "Unique name for this table within the QQQ Instance"
|
|
type: "string"
|
|
readPermission:
|
|
description: "Boolean to indicate if the user has read permission for the\
|
|
\ table."
|
|
type: "boolean"
|
|
variantTableLabel:
|
|
description: "If the table uses variants, this is the user-facing label\
|
|
\ for the table that supplies variants for this table."
|
|
type: "string"
|
|
type: "object"
|
|
WidgetBlock:
|
|
properties:
|
|
blockId:
|
|
description: "Unique identifier for this block within it widget. Used as\
|
|
\ a key for helpContents."
|
|
type: "string"
|
|
blockType:
|
|
description: "What type of block to render."
|
|
enum:
|
|
- "BUTTON"
|
|
- "AUDIO"
|
|
- "BIG_NUMBER"
|
|
- "COMPOSITE"
|
|
- "DIVIDER"
|
|
- "IMAGE"
|
|
- "INPUT_FIELD"
|
|
- "NUMBER_ICON_BADGE"
|
|
- "PROGRESS_BAR"
|
|
- "TABLE_SUB_ROW_DETAIL_ROW"
|
|
- "TEXT"
|
|
- "UP_OR_DOWN_NUMBER"
|
|
type: "string"
|
|
conditional:
|
|
description: "Optional field name (e.g,. from a process's set of fields)\
|
|
\ to act as a 'guard' for the block - e.g., only include it in the UI\
|
|
\ if the value for this field is true"
|
|
type: "string"
|
|
layout:
|
|
description: "For COMPOSITE type blocks, an indicator of how the sub-blocks\
|
|
\ should be laid out"
|
|
enum:
|
|
- "FLEX_COLUMN"
|
|
- "FLEX_ROW_WRAPPED"
|
|
- "FLEX_ROW_SPACE_BETWEEN"
|
|
- "FLEX_ROW_CENTER"
|
|
- "TABLE_SUB_ROW_DETAILS"
|
|
- "BADGES_WRAPPER"
|
|
type: "string"
|
|
modalMode:
|
|
description: "For COMPOSITE type blocks, optional control to make the widget\
|
|
\ appear modally"
|
|
enum:
|
|
- "MODAL"
|
|
type: "string"
|
|
styles:
|
|
$ref: "#/components/schemas/WidgetBlockStyles"
|
|
description: "Styles to apply to the block. Different fields based on blockType."
|
|
oneOf:
|
|
- properties:
|
|
backgroundColor:
|
|
description: "A background color to use for the block"
|
|
type: "string"
|
|
padding:
|
|
description: "Optional padding to apply to the block"
|
|
properties:
|
|
bottom:
|
|
type: "object"
|
|
left:
|
|
type: "object"
|
|
right:
|
|
type: "object"
|
|
top:
|
|
type: "object"
|
|
type: "object"
|
|
type: "object"
|
|
- properties:
|
|
color:
|
|
description: "A Color to use for the button. May be specified as\
|
|
\ a StandardColor (one of: SUCCESS, WARNING, ERROR, INFO, MUTED)\
|
|
\ or an RGB code."
|
|
type: "string"
|
|
format:
|
|
description: "An optional indicator of the screen format preferred\
|
|
\ by the application to be used for this block, such as OUTLINED,\
|
|
\ FILLED, or TEXT. Different frontends may support different formats,\
|
|
\ and implement them differently."
|
|
type: "string"
|
|
type: "object"
|
|
- properties:
|
|
height:
|
|
description: "A request to render the image at a specified height."
|
|
type: "string"
|
|
padding:
|
|
description: "Optional padding to apply to the image"
|
|
properties:
|
|
bottom:
|
|
type: "object"
|
|
left:
|
|
type: "object"
|
|
right:
|
|
type: "object"
|
|
top:
|
|
type: "object"
|
|
type: "object"
|
|
width:
|
|
description: "A request to render the image at a specified width."
|
|
type: "string"
|
|
type: "object"
|
|
- properties:
|
|
color:
|
|
description: "A Color to display the text in. May be specified as\
|
|
\ a StandardColor (one of: SUCCESS, WARNING, ERROR, INFO, MUTED)\
|
|
\ or an RGB code."
|
|
type: "string"
|
|
format:
|
|
description: "An optional indicator of the screen format preferred\
|
|
\ by the application to be used for this block. Different frontends\
|
|
\ may support different formats, and implement them differently."
|
|
type: "string"
|
|
size:
|
|
description: "An optional indicator of the size at which the text\
|
|
\ should be rendered. May be a named value (one oflargest, headline,\
|
|
\ title, body, smallest) or a numeric size - both are up to the\
|
|
\ frontend to interpret."
|
|
type: "string"
|
|
weight:
|
|
description: "An optional indicator of the weight at which the text\
|
|
\ should be rendered. May be a named value (one ofextralight, thin,\
|
|
\ medium, black, semibold, bold, extrabold) or a numeric, e.g.,\
|
|
\ 100, 200, ..., 900"
|
|
type: "string"
|
|
type: "object"
|
|
subBlocks:
|
|
description: "For COMPOSITE type blocks, a list of sub-blocks."
|
|
items:
|
|
$ref: "#/components/schemas/WidgetBlock"
|
|
type: "array"
|
|
values:
|
|
$ref: "#/components/schemas/WidgetBlockValues"
|
|
description: "Values to show in the block, or otherwise control its behavior.\
|
|
\ Different fields based on blockType."
|
|
oneOf:
|
|
- description: "Values used for an AUDIO type widget block"
|
|
properties:
|
|
autoPlay:
|
|
description: "Control if the file should automatically play when the\
|
|
\ block is rendered"
|
|
type: "boolean"
|
|
path:
|
|
description: "The path to the audio file on the server"
|
|
type: "string"
|
|
showControls:
|
|
description: "Control if on-screen controls should be shown to allow\
|
|
\ the user to control playback"
|
|
type: "boolean"
|
|
type: "object"
|
|
- description: "Values used for a BUTTON type widget block"
|
|
properties:
|
|
actionCode:
|
|
description: "Code used within the app as the value submitted when\
|
|
\ the button is clicked"
|
|
type: "string"
|
|
controlCode:
|
|
description: "Instructions for what should happen in the frontend\
|
|
\ (e.g., within a screen), when the button is clicked.\n\nTo show\
|
|
\ a modal composite block, use format: `showModal:${blockId}` (e.g.,\
|
|
\ `showModal:myBlock`)\n\nTo hide a modal composite block, use format:\
|
|
\ `hideModal:${blockId}` (e.g., `hideModal:myBlock`)\n\nTo toggle\
|
|
\ visibility of a modal composite block, use format: `toggleModal:${blockId}`\
|
|
\ (e.g., `toggleModal:myBlock`)\n"
|
|
type: "string"
|
|
endIcon:
|
|
description: "An optional icon to display after the text in the button"
|
|
properties:
|
|
color:
|
|
description: "A color code to use for displaying the icon"
|
|
type: "string"
|
|
name:
|
|
description: "A material UI icon name."
|
|
type: "string"
|
|
path:
|
|
description: "A path to an image file that can be requested from\
|
|
\ the server, to serve as the icon image instead of a material\
|
|
\ UI icon."
|
|
type: "string"
|
|
type: "object"
|
|
label:
|
|
description: "User-facing label to display in the button"
|
|
type: "string"
|
|
startIcon:
|
|
description: "An optional icon to display before the text in the button"
|
|
properties:
|
|
color:
|
|
description: "A color code to use for displaying the icon"
|
|
type: "string"
|
|
name:
|
|
description: "A material UI icon name."
|
|
type: "string"
|
|
path:
|
|
description: "A path to an image file that can be requested from\
|
|
\ the server, to serve as the icon image instead of a material\
|
|
\ UI icon."
|
|
type: "string"
|
|
type: "object"
|
|
type: "object"
|
|
- description: "Values used for an IMAGE type widget block"
|
|
properties:
|
|
path:
|
|
description: "The path to the image on the server"
|
|
type: "string"
|
|
type: "object"
|
|
- description: "Values used for an INPUT_FIELD type widget block"
|
|
properties:
|
|
autoFocus:
|
|
description: "Indicate whether this field should auto-focus when it\
|
|
\ is rendered"
|
|
type: "boolean"
|
|
fieldMetaData:
|
|
description: "Metadata to define the field that this block controls"
|
|
properties:
|
|
adornments:
|
|
description: "Special UI dressings to add to the field."
|
|
items:
|
|
$ref: "#/components/schemas/FieldAdornment"
|
|
type: "array"
|
|
defaultValue:
|
|
description: "Default value to use in this field."
|
|
type: "string"
|
|
displayFormat:
|
|
description: "C-style format specifier for displaying values in\
|
|
\ this field."
|
|
type: "string"
|
|
isEditable:
|
|
description: "Indicate if user may edit the value in this field."
|
|
type: "boolean"
|
|
isHeavy:
|
|
description: "Indicator of 'heavy' fields, which are not loaded\
|
|
\ by default. e.g., some blobs or long-texts"
|
|
type: "boolean"
|
|
isHidden:
|
|
description: "Indicate if this field should be hidden from users"
|
|
type: "boolean"
|
|
isRequired:
|
|
description: "Indicate if a value in this field is required."
|
|
type: "boolean"
|
|
label:
|
|
description: "User-facing name for this field"
|
|
type: "string"
|
|
maxLength:
|
|
description: "For String fields, the max length the field supports."
|
|
type: "number"
|
|
name:
|
|
description: "Unique name for this field within its container\
|
|
\ (table or process)"
|
|
type: "string"
|
|
possibleValueSourceName:
|
|
description: "If this field's values should come from a possible\
|
|
\ value source, then that PVS is named here."
|
|
type: "string"
|
|
type:
|
|
description: "Data-type for this field"
|
|
type: "string"
|
|
type: "object"
|
|
hideSoftKeyboard:
|
|
description: "Indicate if the frontend uses a software/on-screen keyboard,\
|
|
\ if the application should try to hide it (e.g., upon auto-focus)."
|
|
type: "boolean"
|
|
placeholder:
|
|
description: "Optional placeholder text to display in the input box."
|
|
type: "string"
|
|
submitOnEnter:
|
|
description: "Indicate whether the form that this field is on should\
|
|
\ be submitted when Enter is pressed"
|
|
type: "boolean"
|
|
type: "object"
|
|
- description: "Values used for a TEXT type widget block"
|
|
properties:
|
|
endIcon:
|
|
description: "An optional icon to display after the text"
|
|
properties:
|
|
color:
|
|
description: "A color code to use for displaying the icon"
|
|
type: "string"
|
|
name:
|
|
description: "A material UI icon name."
|
|
type: "string"
|
|
path:
|
|
description: "A path to an image file that can be requested from\
|
|
\ the server, to serve as the icon image instead of a material\
|
|
\ UI icon."
|
|
type: "string"
|
|
type: "object"
|
|
startIcon:
|
|
description: "An optional icon to display before the text"
|
|
properties:
|
|
color:
|
|
description: "A color code to use for displaying the icon"
|
|
type: "string"
|
|
name:
|
|
description: "A material UI icon name."
|
|
type: "string"
|
|
path:
|
|
description: "A path to an image file that can be requested from\
|
|
\ the server, to serve as the icon image instead of a material\
|
|
\ UI icon."
|
|
type: "string"
|
|
type: "object"
|
|
text:
|
|
description: "The text to display in the block"
|
|
type: "string"
|
|
type: "object"
|
|
type: "object"
|
|
WidgetBlockAudioValues:
|
|
description: "Values used for an AUDIO type widget block"
|
|
properties:
|
|
autoPlay:
|
|
description: "Control if the file should automatically play when the block\
|
|
\ is rendered"
|
|
type: "boolean"
|
|
path:
|
|
description: "The path to the audio file on the server"
|
|
type: "string"
|
|
showControls:
|
|
description: "Control if on-screen controls should be shown to allow the\
|
|
\ user to control playback"
|
|
type: "boolean"
|
|
type: "object"
|
|
WidgetBlockBaseStyles:
|
|
properties:
|
|
backgroundColor:
|
|
description: "A background color to use for the block"
|
|
type: "string"
|
|
padding:
|
|
description: "Optional padding to apply to the block"
|
|
properties:
|
|
bottom:
|
|
type: "object"
|
|
left:
|
|
type: "object"
|
|
right:
|
|
type: "object"
|
|
top:
|
|
type: "object"
|
|
type: "object"
|
|
type: "object"
|
|
WidgetBlockButtonStyles:
|
|
properties:
|
|
color:
|
|
description: "A Color to use for the button. May be specified as a StandardColor\
|
|
\ (one of: SUCCESS, WARNING, ERROR, INFO, MUTED) or an RGB code."
|
|
type: "string"
|
|
format:
|
|
description: "An optional indicator of the screen format preferred by the\
|
|
\ application to be used for this block, such as OUTLINED, FILLED, or\
|
|
\ TEXT. Different frontends may support different formats, and implement\
|
|
\ them differently."
|
|
type: "string"
|
|
type: "object"
|
|
WidgetBlockButtonValues:
|
|
description: "Values used for a BUTTON type widget block"
|
|
properties:
|
|
actionCode:
|
|
description: "Code used within the app as the value submitted when the button\
|
|
\ is clicked"
|
|
type: "string"
|
|
controlCode:
|
|
description: "Instructions for what should happen in the frontend (e.g.,\
|
|
\ within a screen), when the button is clicked.\n\nTo show a modal composite\
|
|
\ block, use format: `showModal:${blockId}` (e.g., `showModal:myBlock`)\n\
|
|
\nTo hide a modal composite block, use format: `hideModal:${blockId}`\
|
|
\ (e.g., `hideModal:myBlock`)\n\nTo toggle visibility of a modal composite\
|
|
\ block, use format: `toggleModal:${blockId}` (e.g., `toggleModal:myBlock`)\n"
|
|
type: "string"
|
|
endIcon:
|
|
$ref: "#/components/schemas/Icon"
|
|
description: "An optional icon to display after the text in the button"
|
|
label:
|
|
description: "User-facing label to display in the button"
|
|
type: "string"
|
|
startIcon:
|
|
$ref: "#/components/schemas/Icon"
|
|
description: "An optional icon to display before the text in the button"
|
|
type: "object"
|
|
WidgetBlockImageStyles:
|
|
properties:
|
|
height:
|
|
description: "A request to render the image at a specified height."
|
|
type: "string"
|
|
padding:
|
|
description: "Optional padding to apply to the image"
|
|
properties:
|
|
bottom:
|
|
type: "object"
|
|
left:
|
|
type: "object"
|
|
right:
|
|
type: "object"
|
|
top:
|
|
type: "object"
|
|
type: "object"
|
|
width:
|
|
description: "A request to render the image at a specified width."
|
|
type: "string"
|
|
type: "object"
|
|
WidgetBlockImageValues:
|
|
description: "Values used for an IMAGE type widget block"
|
|
properties:
|
|
path:
|
|
description: "The path to the image on the server"
|
|
type: "string"
|
|
type: "object"
|
|
WidgetBlockInputFieldValues:
|
|
description: "Values used for an INPUT_FIELD type widget block"
|
|
properties:
|
|
autoFocus:
|
|
description: "Indicate whether this field should auto-focus when it is rendered"
|
|
type: "boolean"
|
|
fieldMetaData:
|
|
$ref: "#/components/schemas/FieldMetaData"
|
|
description: "Metadata to define the field that this block controls"
|
|
hideSoftKeyboard:
|
|
description: "Indicate if the frontend uses a software/on-screen keyboard,\
|
|
\ if the application should try to hide it (e.g., upon auto-focus)."
|
|
type: "boolean"
|
|
placeholder:
|
|
description: "Optional placeholder text to display in the input box."
|
|
type: "string"
|
|
submitOnEnter:
|
|
description: "Indicate whether the form that this field is on should be\
|
|
\ submitted when Enter is pressed"
|
|
type: "boolean"
|
|
type: "object"
|
|
WidgetBlockStyles:
|
|
type: "object"
|
|
WidgetBlockTextStyles:
|
|
properties:
|
|
color:
|
|
description: "A Color to display the text in. May be specified as a StandardColor\
|
|
\ (one of: SUCCESS, WARNING, ERROR, INFO, MUTED) or an RGB code."
|
|
type: "string"
|
|
format:
|
|
description: "An optional indicator of the screen format preferred by the\
|
|
\ application to be used for this block. Different frontends may support\
|
|
\ different formats, and implement them differently."
|
|
type: "string"
|
|
size:
|
|
description: "An optional indicator of the size at which the text should\
|
|
\ be rendered. May be a named value (one oflargest, headline, title,\
|
|
\ body, smallest) or a numeric size - both are up to the frontend to interpret."
|
|
type: "string"
|
|
weight:
|
|
description: "An optional indicator of the weight at which the text should\
|
|
\ be rendered. May be a named value (one ofextralight, thin, medium,\
|
|
\ black, semibold, bold, extrabold) or a numeric, e.g., 100, 200, ...,\
|
|
\ 900"
|
|
type: "string"
|
|
type: "object"
|
|
WidgetBlockTextValues:
|
|
description: "Values used for a TEXT type widget block"
|
|
properties:
|
|
endIcon:
|
|
$ref: "#/components/schemas/Icon"
|
|
description: "An optional icon to display after the text"
|
|
startIcon:
|
|
$ref: "#/components/schemas/Icon"
|
|
description: "An optional icon to display before the text"
|
|
text:
|
|
description: "The text to display in the block"
|
|
type: "string"
|
|
type: "object"
|
|
WidgetBlockValues:
|
|
type: "object"
|
|
securitySchemes:
|
|
sessionUuidCookie:
|
|
in: "cookie"
|
|
name: "sessionUUID"
|
|
type: "apiKey"
|
|
info:
|
|
contact:
|
|
email: "contact@kingsrook.com"
|
|
description: "## Intro\nThis is the definition of the standard API implemented by\
|
|
\ QQQ Middleware.\n\nDevelopers of QQQ Frontends (e.g., javascript libraries,\
|
|
\ or native applications) use this API to access\na QQQ Backend server.\n\nAs\
|
|
\ such, this API itself is not concerned with any of the application-level details\
|
|
\ of any particular\napplication built using QQQ. Instead, this API is all about\
|
|
\ the generic endpoints used for any application\nbuilt on QQQ. For example,\
|
|
\ many endpoints work with a `${table}` path parameter - whose possible values\n\
|
|
are defined by the application - but which are not known to this API.\n\n## Flow\n\
|
|
The typical flow of a user (as implemented in a frontend that utilizes this API)\
|
|
\ looks like:\n1. Frontend calls `.../metaData/authentication`, to know what type\
|
|
\ of authentication provider is used by the backend, and display an appropriate\
|
|
\ UI to the user for authenticating.\n2. User authenticates in frontend, as required\
|
|
\ for the authentication provider.\n3. Frontend calls `.../manageSession`, providing\
|
|
\ authentication details (e.g., an accessToken or other credentials) to the backend.\n\
|
|
4. The response from the `manageSession` call (assuming success), sets the `sessionUUID`\
|
|
\ Cookie, which should be included in all subsequent requests for authentication.\n\
|
|
5. After the user is authenticated, the frontend calls `.../metaData`, to discover\
|
|
\ the apps, tables, processes, etc, that the application is made up of (and that\
|
|
\ the authenticated user has permission to access).\n6. As the user interacts\
|
|
\ with apps, tables, process, etc, the frontend utilizes the appropriate endpoints\
|
|
\ as required.\n"
|
|
title: "QQQ Middleware API"
|
|
version: "v1"
|
|
openapi: "3.0.3"
|
|
paths:
|
|
/qqq/v1/metaData/authentication:
|
|
get:
|
|
description: "For a frontend to determine which authentication provider or mechanism\
|
|
\ to use, it should begin its lifecycle\nby requesting this metaData object,\
|
|
\ and inspecting the `type` property in the response.\n\nNote that this endpoint\
|
|
\ is not secured, as its purpose is to be called as part of the workflow that\
|
|
\ results\nin a user being authenticated."
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
examples:
|
|
For FULLY_ANONYMOUS type:
|
|
value:
|
|
name: "anonymous"
|
|
type: "FULLY_ANONYMOUS"
|
|
For AUTH_0 type:
|
|
value:
|
|
name: "auth0"
|
|
type: "AUTH_0"
|
|
values:
|
|
audience: "myapp.mydomain.com"
|
|
baseUrl: "https://myapp.auth0.com/"
|
|
clientId: "abcdefg1234567"
|
|
schema:
|
|
$ref: "#/components/schemas/AuthenticationMetaDataResponseV1"
|
|
description: "Successful Response"
|
|
summary: "Get authentication metaData"
|
|
tags:
|
|
- "Authentication"
|
|
/qqq/v1/manageSession:
|
|
post:
|
|
description: "After a frontend authenticates the user as per the requirements\
|
|
\ of the authentication provider specified by the\n`type` field in the `metaData/authentication`\
|
|
\ response, data from that authentication provider should be posted\nto this\
|
|
\ endpoint, to create a session within the QQQ application.\n\nThe response\
|
|
\ object will include a session identifier (`uuid`) to authenticate the user\
|
|
\ in subsequent API calls."
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: "Data required to create the session. Specific needs may\
|
|
\ vary based on the AuthenticationModule type in the QQQ Backend."
|
|
properties:
|
|
accessToken:
|
|
description: "An access token from a downstream authentication provider\
|
|
\ (e.g., Auth0), to use as the basis for authentication and authorization."
|
|
type: "string"
|
|
type: "object"
|
|
required: true
|
|
responses:
|
|
401:
|
|
content:
|
|
application/json:
|
|
examples:
|
|
Invalid token:
|
|
value:
|
|
error: "Unable to decode access token."
|
|
schema:
|
|
$ref: "#/components/schemas/BasicErrorResponseV1"
|
|
description: "Authentication error - session was not created"
|
|
200:
|
|
content:
|
|
application/json:
|
|
examples:
|
|
With no custom values:
|
|
value:
|
|
uuid: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
With custom values:
|
|
value:
|
|
uuid: "98765432-10FE-DCBA-9876-543210FEDCBA"
|
|
values:
|
|
region: "US"
|
|
userCategoryId: 47
|
|
schema:
|
|
$ref: "#/components/schemas/ManageSessionResponseV1"
|
|
description: "Successful response - session has been created"
|
|
summary: "Create a session"
|
|
tags:
|
|
- "Authentication"
|
|
/qqq/v1/metaData:
|
|
get:
|
|
description: "Load the overall metadata, as is relevant to a frontend, for the\
|
|
\ entire application, with permissions applied, as per the\nauthenticated\
|
|
\ user.\n\nThis includes:\n- Apps (both as a map of name to AppMetaData (`apps`),\
|
|
\ but also as a tree (`appTree`), for presenting\nhierarchical navigation),\n\
|
|
- Tables (but without all details, e.g., fields),\n- Processes (also without\
|
|
\ full details, e.g., screens),\n- Reports\n- Widgets\n- Branding\n- Help\
|
|
\ Contents\n- Environment values\n"
|
|
parameters:
|
|
- description: "Name of the frontend requesting the meta-data.\nGenerally a\
|
|
\ QQQ frontend library, unless a custom application frontend has been built."
|
|
example: "qqq-frontend-material-dashboard"
|
|
in: "query"
|
|
name: "frontendName"
|
|
schema:
|
|
type: "string"
|
|
- description: "Version of the frontend requesting the meta-data."
|
|
example: "0.23.0"
|
|
in: "query"
|
|
name: "frontendVersion"
|
|
schema:
|
|
type: "string"
|
|
- description: "Name of the application requesting the meta-data. e.g., an\
|
|
\ instance of a specific frontend\n(i.e., an application might be deployed\
|
|
\ with 2 different qqq-frontend-material-dashboard frontends,\nin which\
|
|
\ case this attribute allows differentiation between them)."
|
|
example: "my-admin-web-app"
|
|
in: "query"
|
|
name: "applicationName"
|
|
schema:
|
|
type: "string"
|
|
- description: "Version of the application requesting the meta-data."
|
|
example: "20241021"
|
|
in: "query"
|
|
name: "applicationVersion"
|
|
schema:
|
|
type: "string"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
examples:
|
|
Example:
|
|
value:
|
|
appTree:
|
|
- children:
|
|
- children:
|
|
- icon:
|
|
name: "person_add"
|
|
label: "Sample Person Process"
|
|
name: "samplePersonProcess"
|
|
type: "PROCESS"
|
|
icon:
|
|
name: "child_friendly"
|
|
label: "Child App"
|
|
name: "childApp"
|
|
type: "APP"
|
|
- icon:
|
|
name: "person_outline"
|
|
label: "Person"
|
|
name: "person"
|
|
type: "TABLE"
|
|
icon:
|
|
name: "home"
|
|
label: "Home App"
|
|
name: "homeApp"
|
|
type: "APP"
|
|
apps:
|
|
homeApp:
|
|
childMap:
|
|
person:
|
|
icon:
|
|
name: "person_outline"
|
|
label: "Person"
|
|
name: "person"
|
|
type: "TABLE"
|
|
childApp:
|
|
icon:
|
|
name: "child_friendly"
|
|
label: "Child App"
|
|
name: "childApp"
|
|
type: "APP"
|
|
children:
|
|
- icon:
|
|
name: "child_friendly"
|
|
label: "Child App"
|
|
name: "childApp"
|
|
type: "APP"
|
|
- icon:
|
|
name: "person_outline"
|
|
label: "Person"
|
|
name: "person"
|
|
type: "TABLE"
|
|
icon:
|
|
name: "home"
|
|
label: "Home App"
|
|
name: "homeApp"
|
|
sections:
|
|
- icon:
|
|
name: "badge"
|
|
label: "Home App"
|
|
name: "homeApp"
|
|
tables:
|
|
- "person"
|
|
childApp:
|
|
childMap:
|
|
samplePersonProcess:
|
|
icon:
|
|
name: "person_add"
|
|
label: "Sample Person Process"
|
|
name: "samplePersonProcess"
|
|
type: "PROCESS"
|
|
children:
|
|
- icon:
|
|
name: "person_add"
|
|
label: "Sample Person Process"
|
|
name: "samplePersonProcess"
|
|
type: "PROCESS"
|
|
icon:
|
|
name: "child_friendly"
|
|
label: "Child App"
|
|
name: "childApp"
|
|
sections:
|
|
- icon:
|
|
name: "badge"
|
|
label: "Child App"
|
|
name: "childApp"
|
|
processes:
|
|
- "samplePersonProcess"
|
|
processes:
|
|
person.bulkInsert:
|
|
hasPermission: true
|
|
icon:
|
|
name: "library_add"
|
|
isHidden: true
|
|
label: "Person Bulk Insert"
|
|
name: "person.bulkInsert"
|
|
stepFlow: "LINEAR"
|
|
tableName: "person"
|
|
person.bulkEdit:
|
|
hasPermission: true
|
|
isHidden: true
|
|
label: "Person Bulk Edit"
|
|
name: "person.bulkEdit"
|
|
stepFlow: "LINEAR"
|
|
tableName: "person"
|
|
samplePersonProcess:
|
|
hasPermission: true
|
|
icon:
|
|
name: "person_add"
|
|
isHidden: false
|
|
label: "Sample Person Process"
|
|
name: "samplePersonProcess"
|
|
stepFlow: "LINEAR"
|
|
tableName: "person"
|
|
person.bulkDelete:
|
|
hasPermission: true
|
|
isHidden: true
|
|
label: "Person Bulk Delete"
|
|
name: "person.bulkDelete"
|
|
stepFlow: "LINEAR"
|
|
tableName: "person"
|
|
person.bulkEditWithFile:
|
|
hasPermission: true
|
|
isHidden: true
|
|
label: "Person Bulk Edit With File"
|
|
name: "person.bulkEditWithFile"
|
|
stepFlow: "LINEAR"
|
|
tableName: "person"
|
|
tables:
|
|
person:
|
|
capabilities:
|
|
- "TABLE_COUNT"
|
|
- "TABLE_GET"
|
|
- "TABLE_QUERY"
|
|
- "QUERY_STATS"
|
|
- "TABLE_INSERT"
|
|
- "TABLE_UPDATE"
|
|
- "TABLE_DELETE"
|
|
deletePermission: true
|
|
editPermission: true
|
|
icon:
|
|
name: "person_outline"
|
|
insertPermission: true
|
|
isHidden: false
|
|
label: "Person"
|
|
name: "person"
|
|
readPermission: true
|
|
schema:
|
|
$ref: "#/components/schemas/MetaDataResponseV1"
|
|
description: "Overall metadata for the application."
|
|
security:
|
|
- sessionUuidCookie:
|
|
- "N/A"
|
|
summary: "Get instance metaData"
|
|
tags:
|
|
- "General"
|
|
/qqq/v1/metaData/process/{processName}:
|
|
get:
|
|
description: "Load the full metadata for a single process, including all screens\
|
|
\ (aka, frontend steps), which a frontend\nneeds to display to users."
|
|
parameters:
|
|
- description: "Name of the process to load."
|
|
example: "samplePersonProcess"
|
|
in: "path"
|
|
name: "processName"
|
|
required: true
|
|
schema:
|
|
type: "string"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
examples:
|
|
TODO:
|
|
value: {}
|
|
schema:
|
|
$ref: "#/components/schemas/ProcessMetaDataResponseV1"
|
|
description: "The full process metadata"
|
|
security:
|
|
- sessionUuidCookie:
|
|
- "N/A"
|
|
summary: "Get process metaData"
|
|
tags:
|
|
- "Processes"
|
|
/qqq/v1/processes/{processName}/init:
|
|
post:
|
|
description: "For a user to start running a process, this endpoint should be\
|
|
\ called, to start the process\nand run its first step(s) (any backend steps\
|
|
\ before the first frontend step).\n\nAdditional process-specific values should\
|
|
\ posted in a form param named `values`, as JSON object\nwith keys defined\
|
|
\ by the process in question.\n\nFor a process which needs to operate on a\
|
|
\ set of records that a user selected, see\n`recordsParam`, and `recordIds`\
|
|
\ or `filterJSON`.\n\nThe response will include a `processUUID`, to be included\
|
|
\ in all subsequent requests relevant\nto the process.\n\nNote that this request,\
|
|
\ if it takes longer than a given threshold* to complete, will return a\n\
|
|
a `jobUUID`, which should be sent to the `/processes/{processName}/{processUUID}/status/{jobUUID}`\n\
|
|
endpoint, to poll for a status update.\n\n*This threshold has a default value\
|
|
\ of 3,000 ms., but can be set per-request via the form\nparameter `stepTimeoutMillis`.\n"
|
|
parameters:
|
|
- description: "Name of the process to initialize"
|
|
example: "samplePersonProcess"
|
|
in: "path"
|
|
name: "processName"
|
|
required: true
|
|
schema:
|
|
type: "string"
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
properties:
|
|
values:
|
|
description: "Process-specific field names and values."
|
|
type: "object"
|
|
recordsParam:
|
|
description: "Specifies which other query-param will contain the\
|
|
\ indicator of initial records to pass in to the process."
|
|
examples:
|
|
recordIds:
|
|
value: "recordIds"
|
|
filterJSON:
|
|
value: "recordIds"
|
|
type: "string"
|
|
recordIds:
|
|
description: "Comma-separated list of ids from the table this process\
|
|
\ is based on, to use as input records for the process. Needs\
|
|
\ `recordsParam=recordIds` value to be given as well."
|
|
examples:
|
|
one id:
|
|
value: "1701"
|
|
multiple ids:
|
|
value: "42,47"
|
|
type: "string"
|
|
filterJSON:
|
|
description: "JSON encoded QQueryFilter object, to execute against\
|
|
\ the table this process is based on, to find input records for\
|
|
\ the process. Needs `recordsParam=filterJSON` value to be given\
|
|
\ as well."
|
|
examples:
|
|
empty filter (all records):
|
|
value: "{}"
|
|
filter by a condition:
|
|
value: "{\"criteria\":[{\"fieldName\":\"id\",\"operator\":\"\
|
|
LESS_THAN\",\"values\":[10]}],\"booleanOperator\":\"AND\"}"
|
|
type: "string"
|
|
stepTimeoutMillis:
|
|
description: "Optionally change the time that the server will wait\
|
|
\ for the job before letting it go asynchronous. Default value\
|
|
\ is 3000."
|
|
examples:
|
|
shorter timeout:
|
|
value: "500"
|
|
longer timeout:
|
|
value: "60000"
|
|
type: "integer"
|
|
file:
|
|
description: "A file upload, for processes which expect to be initialized\
|
|
\ with an uploaded file."
|
|
format: "binary"
|
|
type: "string"
|
|
type: "object"
|
|
required: false
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
examples:
|
|
COMPLETE:
|
|
value:
|
|
values:
|
|
firstLastName: "Aabramson"
|
|
totalAge: 32768
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
nextStep: "reviewScreen"
|
|
type: "COMPLETE"
|
|
COMPLETE with metaDataAdjustment:
|
|
value:
|
|
values:
|
|
firstLastName: "Aabramson"
|
|
totalAge: 32768
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
nextStep: "inputScreen"
|
|
processMetaDataAdjustment:
|
|
updatedFields:
|
|
someField:
|
|
isRequired: true
|
|
isEditable: true
|
|
name: "someField"
|
|
displayFormat: "%s"
|
|
type: "STRING"
|
|
isHeavy: false
|
|
isHidden: false
|
|
updatedFrontendStepList:
|
|
- components:
|
|
- type: "EDIT_FORM"
|
|
name: "inputScreen"
|
|
formFields:
|
|
- isRequired: false
|
|
isEditable: true
|
|
name: "someField"
|
|
displayFormat: "%s"
|
|
type: "STRING"
|
|
isHeavy: false
|
|
isHidden: false
|
|
- components:
|
|
- type: "PROCESS_SUMMARY_RESULTS"
|
|
name: "resultScreen"
|
|
type: "COMPLETE"
|
|
JOB_STARTED:
|
|
value:
|
|
jobUUID: "98765432-10FE-DCBA-9876-543210FEDCBA"
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
type: "JOB_STARTED"
|
|
RUNNING:
|
|
value:
|
|
current: 47
|
|
total: 1701
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
type: "RUNNING"
|
|
message: "Processing person records"
|
|
ERROR:
|
|
value:
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
type: "RUNNING"
|
|
schema:
|
|
$ref: "#/components/schemas/ProcessStepResponseV1"
|
|
description: "State of the initialization of the job, with different fields\
|
|
\ set, based on the\nstatus of the task."
|
|
security:
|
|
- sessionUuidCookie:
|
|
- "N/A"
|
|
summary: "Initialize a process"
|
|
tags:
|
|
- "Processes"
|
|
/qqq/v1/processes/{processName}/{processUUID}/step/{stepName}:
|
|
post:
|
|
description: "To run the next step in a process, this endpoint should be called,\
|
|
\ with the `processName`\nand existing `processUUID`, as well as the step\
|
|
\ that was just completed in the frontend,\ngiven as `stepName`.\n\nAdditional\
|
|
\ process-specific values should posted in a form param named `values`, as\
|
|
\ JSON object\nwith keys defined by the process in question.\n\nNote that\
|
|
\ this request, if it takes longer than a given threshold* to complete, will\
|
|
\ return a\na `jobUUID`, which should be sent to the `/processes/{processName}/{processUUID}/status/{jobUUID}`\n\
|
|
endpoint, to poll for a status update.\n\n*This threshold has a default value\
|
|
\ of 3,000 ms., but can be set per-request via the form\nparameter `stepTimeoutMillis`.\n"
|
|
parameters:
|
|
- description: "Name of the process to perform the step in."
|
|
example: "samplePersonProcess"
|
|
in: "path"
|
|
name: "processName"
|
|
required: true
|
|
schema:
|
|
type: "string"
|
|
- description: "Unique identifier for this run of the process - as was returned\
|
|
\ by the `init` call."
|
|
example: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
in: "path"
|
|
name: "processUUID"
|
|
required: true
|
|
schema:
|
|
type: "string"
|
|
- description: "Name of the frontend step that the user has just completed."
|
|
example: "inputForm"
|
|
in: "path"
|
|
name: "stepName"
|
|
required: true
|
|
schema:
|
|
type: "string"
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
properties:
|
|
values:
|
|
description: "Process-specific field names and values."
|
|
type: "object"
|
|
stepTimeoutMillis:
|
|
description: "Optionally change the time that the server will wait\
|
|
\ for the job before letting it go asynchronous. Default value\
|
|
\ is 3000."
|
|
examples:
|
|
shorter timeout:
|
|
value: "500"
|
|
longer timeout:
|
|
value: "60000"
|
|
type: "integer"
|
|
file:
|
|
description: "A file upload, for process steps which expect an uploaded\
|
|
\ file."
|
|
format: "binary"
|
|
type: "string"
|
|
type: "object"
|
|
required: false
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
examples:
|
|
COMPLETE:
|
|
value:
|
|
values:
|
|
firstLastName: "Aabramson"
|
|
totalAge: 32768
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
nextStep: "reviewScreen"
|
|
type: "COMPLETE"
|
|
COMPLETE with metaDataAdjustment:
|
|
value:
|
|
values:
|
|
firstLastName: "Aabramson"
|
|
totalAge: 32768
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
nextStep: "inputScreen"
|
|
processMetaDataAdjustment:
|
|
updatedFields:
|
|
someField:
|
|
isRequired: true
|
|
isEditable: true
|
|
name: "someField"
|
|
displayFormat: "%s"
|
|
type: "STRING"
|
|
isHeavy: false
|
|
isHidden: false
|
|
updatedFrontendStepList:
|
|
- components:
|
|
- type: "EDIT_FORM"
|
|
name: "inputScreen"
|
|
formFields:
|
|
- isRequired: false
|
|
isEditable: true
|
|
name: "someField"
|
|
displayFormat: "%s"
|
|
type: "STRING"
|
|
isHeavy: false
|
|
isHidden: false
|
|
- components:
|
|
- type: "PROCESS_SUMMARY_RESULTS"
|
|
name: "resultScreen"
|
|
type: "COMPLETE"
|
|
JOB_STARTED:
|
|
value:
|
|
jobUUID: "98765432-10FE-DCBA-9876-543210FEDCBA"
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
type: "JOB_STARTED"
|
|
RUNNING:
|
|
value:
|
|
current: 47
|
|
total: 1701
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
type: "RUNNING"
|
|
message: "Processing person records"
|
|
ERROR:
|
|
value:
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
type: "RUNNING"
|
|
schema:
|
|
$ref: "#/components/schemas/ProcessStepResponseV1"
|
|
description: "State of the backend's running of the next step(s) of the\
|
|
\ job, with different fields set,\nbased on the status of the job."
|
|
security:
|
|
- sessionUuidCookie:
|
|
- "N/A"
|
|
summary: "Run a step in a process"
|
|
tags:
|
|
- "Processes"
|
|
/qqq/v1/processes/{processName}/{processUUID}/status/{jobUUID}:
|
|
get:
|
|
description: "Get the status of a running job for a process.\n\nResponse is\
|
|
\ the same format as for an init or step call that completed synchronously.\n"
|
|
parameters:
|
|
- description: "Name of the process that is being ran"
|
|
example: "samplePersonProcess"
|
|
in: "path"
|
|
name: "processName"
|
|
required: true
|
|
schema:
|
|
type: "string"
|
|
- description: "Unique identifier for this run of the process - as was returned\
|
|
\ by the `init` call."
|
|
example: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
in: "path"
|
|
name: "processUUID"
|
|
required: true
|
|
schema:
|
|
format: "uuid"
|
|
type: "string"
|
|
- description: "Unique identifier for the asynchronous job being executed, as\
|
|
\ returned by an `init` or `step` call that went asynch."
|
|
example: "98765432-10FE-DCBA-9876-543210FEDCBA"
|
|
in: "path"
|
|
name: "jobUUID"
|
|
required: true
|
|
schema:
|
|
format: "uuid"
|
|
type: "string"
|
|
responses:
|
|
200:
|
|
content:
|
|
application/json:
|
|
examples:
|
|
COMPLETE:
|
|
value:
|
|
values:
|
|
firstLastName: "Aabramson"
|
|
totalAge: 32768
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
nextStep: "reviewScreen"
|
|
type: "COMPLETE"
|
|
COMPLETE with metaDataAdjustment:
|
|
value:
|
|
values:
|
|
firstLastName: "Aabramson"
|
|
totalAge: 32768
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
nextStep: "inputScreen"
|
|
processMetaDataAdjustment:
|
|
updatedFields:
|
|
someField:
|
|
isRequired: true
|
|
isEditable: true
|
|
name: "someField"
|
|
displayFormat: "%s"
|
|
type: "STRING"
|
|
isHeavy: false
|
|
isHidden: false
|
|
updatedFrontendStepList:
|
|
- components:
|
|
- type: "EDIT_FORM"
|
|
name: "inputScreen"
|
|
formFields:
|
|
- isRequired: false
|
|
isEditable: true
|
|
name: "someField"
|
|
displayFormat: "%s"
|
|
type: "STRING"
|
|
isHeavy: false
|
|
isHidden: false
|
|
- components:
|
|
- type: "PROCESS_SUMMARY_RESULTS"
|
|
name: "resultScreen"
|
|
type: "COMPLETE"
|
|
JOB_STARTED:
|
|
value:
|
|
jobUUID: "98765432-10FE-DCBA-9876-543210FEDCBA"
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
type: "JOB_STARTED"
|
|
RUNNING:
|
|
value:
|
|
current: 47
|
|
total: 1701
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
type: "RUNNING"
|
|
message: "Processing person records"
|
|
ERROR:
|
|
value:
|
|
processUUID: "01234567-89AB-CDEF-0123-456789ABCDEF"
|
|
type: "RUNNING"
|
|
schema:
|
|
$ref: "#/components/schemas/ProcessStepResponseV1"
|
|
description: "State of the backend's running of the specified job, with\
|
|
\ different fields set,\nbased on the status of the job."
|
|
security:
|
|
- sessionUuidCookie:
|
|
- "N/A"
|
|
summary: "Get job status"
|
|
tags:
|
|
- "Processes"
|