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" 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"