Optional
options: ApiOptionsBroadcast an event to CatalogIQ.
Make the entire CatalogIQ fullscreen.
Exit fullscreen mode.
Get the request types.
Return is CatalogIQ in fullscreen.
Log out the current user.
Unsubscribe from a given event type by its key and the attached callback reference.
Subscribe to a given event type by its key.
Quit the current instance and go to the instance selection screen.
Subscribe to updates.
Unsubscribe from updates.
Creates a new folder.
The folder creation request payload, excluding the instance_id.
A promise that resolves to the created folder.
Deletes a folder.
An object containing the ID of the folder to delete.
The ID of the folder to delete.
A promise that resolves when the folder is deleted.
Fetches a list of canvases to use in your app.
// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
api.getCanvases({
search: 'my search query',
ordering: '-created_at',
filters: {
metadata__mydaterangefiltername__range: ['2023-12-10', '2023-12-22'],
metadata__mymultiselectfiltername: ['optionAValue', 'optionCValue'],
},
fields: 'id,name,metadata',
})
Fetches the necessary info for the app to know where it is embedded.
It contains information about:
Get a list of favorites
Optional
payload: GetFavoritesParamsOptional
content_type?: FileContentTypeEnum | FileContentTypeEnum[]Filter for content types.
Optional
created_at__range?: stringRange filter for creation date.
Optional
expires_at__range?: stringRange filter for expiration date.
Optional
id__in?: stringFilter for file IDs.
Optional
type?: FileTypeEnum | FileTypeEnum[]Filter for file types.
Optional
updated_at__range?: stringRange filter for update date.
Optional
fields?: stringOptional
filters?: Record<string, any>Retrieves a folder by its ID.
An object containing the folder ID.
The ID of the folder to retrieve. Defaults to 'root'.
A promise that resolves to the retrieved folder.
Retrieves a list of folders.
The payload containing the search, ordering, filters, fields, name, page, and page_size.
A promise that resolves to the list of folders.
Optional
payload: GetInstanceMetadataTemplatesPayloadOptional
payload: GetRecentFilesPayloadOptional
payload: GetUsersParamsMoves items (files or folders) to a target folder.
The payload containing the target folder ID and items to move.
An array of items to move, each with an ID and type.
The ID of the target folder.
A promise that resolves to the updated target folder.
Open a file in the CatalogIQ instance.
Open external URL in a new tab. Works on both web and mobile.
Ask for a refreshed Salesforce token. In case the token hasn't expired yet, this method will return the same token as the current one found in the (getEnv
)[#getenv] result.
Optional
payload: RefreshServiceTokenRequestPromise resolving to an object containing the token
Renders a page from a file together with annotations.
Optional
documentId?: stringThe ID of the document to render (optional). If not provided the fileId will be used.
The ID of the file to render. Used when the documentId is not available.
The index of the page to render.
The parameters to use for rendering the page.
A promise that resolves with the image as an ArrayBuffer.
Dispatches iOS native file selector and returns the selected file.
Dispatches iOS only sync method for non-files.
Updates a canvas by ID
Updates canvas indicators by canvas ID. It merges the passed object into existing canvas indicators adding new keys if they were empty and overriding pre-existing keys.
Indicators can also be updated using updateCanvas API but in this case passed object fully replaces existing indicators.
// The fields param is appended to the URL as a query param.
onMounted(() => {
PitcherAPI.updateCanvasIndicators({
id: '01J9XT0WVXRTETF4CQZP42CPZP',
indicators: {
existing: { type: 'info', label: 'new label' }, // will be overriden
new: { type: 'info', label: 'INFO' }, // will be added
removeExisting: null // will be set to null and ignored, it is the same as removal
}
}).then((res) => {
console.log(res) // entire canvas object, including indicators field
})
})
Updates an existing folder.
The folder update payload, including the folder ID and update data.
A promise that resolves to the updated folder.
Send an app error to Pitcher sentry instance.
error object to send to Pitcher sentry instance
Closes the already open file that was opened via api or by the user.
Fetches a canvas by id with the defined fields or all of them.
Fetches a list of canvases to use in your app.
// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
adminApi.getCanvases({
search: 'my search query',
ordering: '-created_at',
filters: {
metadata__mydaterangefiltername__range: ['2023-12-10', '2023-12-22'],
metadata__mymultiselectfiltername: ['optionAValue', 'optionCValue'],
},
fields: 'id,name,metadata',
})
Fetches the necessary info for the app to know where it is embedded.
Check out usePitcherApi().getEnv() for more information.
Fetches a list of metadata templates to use in your app. Instance is auto-injected by admin app if in instance scope.
Optional
payload: GetInstanceMetadataTemplatesPayloadFetches a list of users from the admin API.
Optional
payload: GetUsersParamsOptional parameters for filtering users
Promise resolving to a paginated list of users
Opens a modal to view a canvas by ID.
onMounted(() => {
adminApi.openCanvasOverlay({
id: '01HH4RCBH631K4JDHWAQB0RPR6',
edit_mode: false,
fullscreen: true,
})
})
You can also specify a position for the canvas overlay:
adminApi.openCanvasOverlay({
id: '01HH4RCBH631K4JDHWAQB0RPR6',
position: {
top: '10px',
left: '20px',
right: '20px',
bottom: '10px'
}
})
Opens the agenda selector modal to allow the user to select agenda content and handle the outcome.
const api = useApi() // or useAdmin() if you know that you 're in Admin context
adminApi.selectAgendaContent({
// optional payload
initial_agenda: {
name: 'test',
groups: []
}
})
Allows the user to select (and preselect) canvases from the instance.
This method allows you to prompt the user to select canvases from the CatalogIQ instance and use that canvas selection in your application.
optional payload to preselect specific canvases
Promise with the user action and selected canvases
const api = useApi() // or useAdmin() if you know that you 're in Admin context
api
.selectCanvases({
allowed_types: ['canvas','canvas-template','section','section-template'] // default ['canvas']
selections: [
{ id: "01HCZ623YYRFJQ0F7B69VWE510" },
{ id: "02HCZ623YYRFJQ0F7B69VWE510" },
], // default []
})
Opens the collection player selector modal to allow the user to select collection player content and handle the outcome.
const api = useApi() // or useAdmin() if you know that you 're in Admin context
adminApi.selectCollectionContent({
// optional payload
initial_data: {
name: 'test',
groups: []
}
})
Opens a selector that allows you to select (and preselect) from your Pitcher uploaded content.
Updates a canvas by ID and returns the defined fields or all of them.
Closes the already open file that was opened via api or by the user.
Signal to DSR that the app is ready to be shown.
Fetches the necessary info for the app to know where it is embedded.
Check out usePitcherApi().getEnv() for more information.
Broadcast an event to CatalogIQ.
Make the entire CatalogIQ fullscreen.
Exit fullscreen mode.
Get the request types.
Broadcast an event to CatalogIQ.
Make the entire CatalogIQ fullscreen.
Exit fullscreen mode.
Get the request types.
Return is CatalogIQ in fullscreen.
Log out the current user.
Unsubscribe from a given event type by its key and the attached callback reference.
Subscribe to a given event type by its key.
Quit the current instance and go to the instance selection screen.
Subscribe to updates.
Unsubscribe from updates.
Creates a new folder.
The folder creation request payload, excluding the instance_id.
A promise that resolves to the created folder.
Deletes a folder.
An object containing the ID of the folder to delete.
The ID of the folder to delete.
A promise that resolves when the folder is deleted.
Fetches a list of canvases to use in your app.
// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
api.getCanvases({
search: 'my search query',
ordering: '-created_at',
filters: {
metadata__mydaterangefiltername__range: ['2023-12-10', '2023-12-22'],
metadata__mymultiselectfiltername: ['optionAValue', 'optionCValue'],
},
fields: 'id,name,metadata',
})
Fetches the necessary info for the app to know where it is embedded.
It contains information about:
Get a list of favorites
Optional
payload: GetFavoritesParamsOptional
content_type?: FileContentTypeEnum | FileContentTypeEnum[]Filter for content types.
Optional
created_at__range?: stringRange filter for creation date.
Optional
expires_at__range?: stringRange filter for expiration date.
Optional
id__in?: stringFilter for file IDs.
Optional
type?: FileTypeEnum | FileTypeEnum[]Filter for file types.
Optional
updated_at__range?: stringRange filter for update date.
Optional
fields?: stringOptional
filters?: Record<string, any>Retrieves a folder by its ID.
An object containing the folder ID.
The ID of the folder to retrieve. Defaults to 'root'.
A promise that resolves to the retrieved folder.
Retrieves a list of folders.
The payload containing the search, ordering, filters, fields, name, page, and page_size.
A promise that resolves to the list of folders.
Optional
payload: GetInstanceMetadataTemplatesPayloadOptional
payload: GetRecentFilesPayloadOptional
payload: GetUsersParamsMoves items (files or folders) to a target folder.
The payload containing the target folder ID and items to move.
An array of items to move, each with an ID and type.
The ID of the target folder.
A promise that resolves to the updated target folder.
Open a file in the CatalogIQ instance.
Open external URL in a new tab. Works on both web and mobile.
Ask for a refreshed Salesforce token. In case the token hasn't expired yet, this method will return the same token as the current one found in the (getEnv
)[#getenv] result.
Optional
payload: RefreshServiceTokenRequestPromise resolving to an object containing the token
Renders a page from a file together with annotations.
Optional
documentId?: stringThe ID of the document to render (optional). If not provided the fileId will be used.
The ID of the file to render. Used when the documentId is not available.
The index of the page to render.
The parameters to use for rendering the page.
A promise that resolves with the image as an ArrayBuffer.
Dispatches iOS native file selector and returns the selected file.
Dispatches iOS only sync method for non-files.
Updates a canvas by ID
Updates canvas indicators by canvas ID. It merges the passed object into existing canvas indicators adding new keys if they were empty and overriding pre-existing keys.
Indicators can also be updated using updateCanvas API but in this case passed object fully replaces existing indicators.
// The fields param is appended to the URL as a query param.
onMounted(() => {
PitcherAPI.updateCanvasIndicators({
id: '01J9XT0WVXRTETF4CQZP42CPZP',
indicators: {
existing: { type: 'info', label: 'new label' }, // will be overriden
new: { type: 'info', label: 'INFO' }, // will be added
removeExisting: null // will be set to null and ignored, it is the same as removal
}
}).then((res) => {
console.log(res) // entire canvas object, including indicators field
})
})
Updates an existing folder.
The folder update payload, including the folder ID and update data.
A promise that resolves to the updated folder.
Return is CatalogIQ in fullscreen.
Log out the current user.
Unsubscribe from a given event type by its key and the attached callback reference.
Quit the current instance and go to the instance selection screen.
Subscribe to updates.
Notify the CatalogIQ instance that the app is loaded and ready to get the data. Triggering this method will trigger
the on_app_set_data
event.
Resize the app iframe to a given height.
Note that initial iframe height comes from the app.json
manifest file. It can also be adjusted by the user when adding
app component to the canvas. In case when the app must be temporarily resized to show larger ui elements it can read the
user-set height from the on_app_set_data event.
object containing requested height of the iframe as the number of pixels
Cancels current meeting and the event remains unrealized (like it never happened).
Navigate to the next page in the current canvas. Noop if the current page is the last one.
Navigate to a specific canvas place in the current canvas. Despite the event and parameter name, it takes the component id that we want to put in view.
const uiApi = useUi() // our useApi()
let activeCanvas = null
const unsubscribe = uiApi.on_app_set_data((data) => {
activeCanvas = data?.canvas
})
document.getElementById('my-button').addEventListener('click', () => {
const target = activeCanvas?.content?.data?.find((i: any) => i.data.app_name === 'my-target-app-id') || null
if (target) {
uiApi.canvasNavigatePage({ page: target.id })
}
})
Navigate to the previous page in the current canvas. Noop if the current page is the first one.
Send an app error to Pitcher sentry instance.
error object to send to Pitcher sentry instance
Close the Canvas Section Execution modal. Only takes effect for canvas_section_execution
app modules
Note that this method simply closes the modal and will result in the app calling it being unmounted from the DOM and destroyed. Make sure your app has finished updating data before you call this method.
Completes the postcall stage (with successful submission or not)
Mark the postcall form as not possible to submit by the user. Useful while processing the form data.
This event is used for appJson.module.canvas.start_in_loading_mode: true apps. A loading curtain is displayed until you call this event.
Mark the postcall form as possible to submit by the user.
Opens a modal to view a canvas by ID.
onMounted(() => {
uiApi.openCanvasOverlay({
id: '01HH4RCBH631K4JDHWAQB0RPR6',
edit_mode: false,
fullscreen: true,
})
})
You can also specify a position for the canvas overlay:
uiApi.openCanvasOverlay({
id: '01HH4RCBH631K4JDHWAQB0RPR6',
position: {
top: '10px',
left: '20px',
right: '20px',
bottom: '10px'
}
})
Preselect a meeting in the top meeting bar by Salesforce Meeting ID. From there, the user can easily start the meeting with a single click.
const objectFetchedFromSalesforce = {
// fetch dynamically from Salesforce or provide in another way
EventId: '00U1r00000D1J1zEAF',
}
ui.preselectSfdcMeetingId({ eventId: objectFetchedFromSalesforce.EventId }).then((response) => {
// e.g. display advanced meeting details inside your app
console.log(response.event)
})
Sends a query to the Pitcher Intelligent Assistant (PIA) and handles the streamed response.
// Subscribe to PIA's streamed responses
const cleanup = await useUi().on(
UI_MESSAGE_TYPES.UI_PROMPT_PIA_RESPONSE_STREAMED,
async ({ chunk, partial_response, id }) => {
console.log(`PIA response chunk for stream ${id}: ${chunk}`);
console.log(`PIA response so far for stream ${id}: ${partial_response}`);
}
);
// Prompt PIA with a question and ensure cleanup is called afterwards
useUi().promptPia({ prompt: "What's my most presented file?", id: 'my-prompt-id-to-discern-with-stream-event' })
.finally(cleanup);
Resumes the meeting and attempts to go at the last presented route / component.
Opens the agenda selector modal to allow the user to select agenda content and handle the outcome.
const api = useApi() // or useUi() if you know that you 're in UI context
uiApi.selectAgendaContent({
// optional payload
initial_agenda: {
name: 'test',
groups: []
}
})
Allows the user to select (and preselect) canvases from the instance.
This method allows you to prompt the user to select canvases from the CatalogIQ instance and use that canvas selection in your application.
optional payload to preselect specific canvases
Promise with the user action and selected canvases
const api = useApi() // or useUi() if you know that you 're in UI context
api
.selectCanvases({
allowed_types: ['canvas','canvas-template','section','section-template'] // default ['canvas']
selections: [
{ id: "01HCZ623YYRFJQ0F7B69VWE510" },
{ id: "02HCZ623YYRFJQ0F7B69VWE510" },
], // default []
})
Opens the collection player selector modal to allow the user to select collection player content and handle the outcome.
const api = useApi() // or useUi() if you know that you 're in UI context
uiApi.selectCollectionContent({
// optional payload
initial_data: {
name: 'test',
groups: []
}
})
Allows the user to select (and preselect) content from the instance.
Opens the content selector dialog to allow the user to select content and handle the outcome. This method allows you to prompt the user to select content from the CatalogIQ instance and use that content in your application.
optional payload to preselect specific content
Promise with the user action and selected content
Change the height of the postcall form.
Modify the currently loaded canvas. On the web it sends an update_canvas request to the server.
parts of the canvas object to update with fields to return
Navigate to another page in the CatalogIQ instance.
Unsubscribe from updates.
Notify the CatalogIQ instance that the app is loaded and ready to get the data. Triggering this method will trigger
the on_app_set_data
event.
Resize the app iframe to a given height.
Note that initial iframe height comes from the app.json
manifest file. It can also be adjusted by the user when adding
app component to the canvas. In case when the app must be temporarily resized to show larger ui elements it can read the
user-set height from the on_app_set_data event.
object containing requested height of the iframe as the number of pixels
Cancels current meeting and the event remains unrealized (like it never happened).
Navigate to the next page in the current canvas. Noop if the current page is the last one.
Navigate to a specific canvas place in the current canvas. Despite the event and parameter name, it takes the component id that we want to put in view.
const uiApi = useUi() // our useApi()
let activeCanvas = null
const unsubscribe = uiApi.on_app_set_data((data) => {
activeCanvas = data?.canvas
})
document.getElementById('my-button').addEventListener('click', () => {
const target = activeCanvas?.content?.data?.find((i: any) => i.data.app_name === 'my-target-app-id') || null
if (target) {
uiApi.canvasNavigatePage({ page: target.id })
}
})
Navigate to the previous page in the current canvas. Noop if the current page is the first one.
Send an app error to Pitcher sentry instance.
error object to send to Pitcher sentry instance
Close the Canvas Section Execution modal. Only takes effect for canvas_section_execution
app modules
Note that this method simply closes the modal and will result in the app calling it being unmounted from the DOM and destroyed. Make sure your app has finished updating data before you call this method.
Completes the postcall stage (with successful submission or not)
Creates a new folder.
The folder creation request payload, excluding the instance_id.
A promise that resolves to the created folder.
Deletes a folder.
An object containing the ID of the folder to delete.
The ID of the folder to delete.
A promise that resolves when the folder is deleted.
Mark the postcall form as not possible to submit by the user. Useful while processing the form data.
This event is used for appJson.module.canvas.start_in_loading_mode: true apps. A loading curtain is displayed until you call this event.
Mark the postcall form as possible to submit by the user.
Fetches a list of canvases to use in your app.
// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
api.getCanvases({
search: 'my search query',
ordering: '-created_at',
filters: {
metadata__mydaterangefiltername__range: ['2023-12-10', '2023-12-22'],
metadata__mymultiselectfiltername: ['optionAValue', 'optionCValue'],
},
fields: 'id,name,metadata',
})
Fetches the necessary info for the app to know where it is embedded.
It contains information about:
Get a list of favorites
Optional
payload: GetFavoritesParamsOptional
content_type?: FileContentTypeEnum | FileContentTypeEnum[]Filter for content types.
Optional
created_at__range?: stringRange filter for creation date.
Optional
expires_at__range?: stringRange filter for expiration date.
Optional
id__in?: stringFilter for file IDs.
Optional
type?: FileTypeEnum | FileTypeEnum[]Filter for file types.
Optional
updated_at__range?: stringRange filter for update date.
Optional
fields?: stringOptional
filters?: Record<string, any>Retrieves a folder by its ID.
An object containing the folder ID.
The ID of the folder to retrieve. Defaults to 'root'.
A promise that resolves to the retrieved folder.
Retrieves a list of folders.
The payload containing the search, ordering, filters, fields, name, page, and page_size.
A promise that resolves to the list of folders.
Optional
payload: GetInstanceMetadataTemplatesPayloadOptional
payload: GetRecentFilesPayloadOptional
payload: GetUsersParamsMoves items (files or folders) to a target folder.
The payload containing the target folder ID and items to move.
An array of items to move, each with an ID and type.
The ID of the target folder.
A promise that resolves to the updated target folder.
Opens a modal to view a canvas by ID.
onMounted(() => {
uiApi.openCanvasOverlay({
id: '01HH4RCBH631K4JDHWAQB0RPR6',
edit_mode: false,
fullscreen: true,
})
})
You can also specify a position for the canvas overlay:
uiApi.openCanvasOverlay({
id: '01HH4RCBH631K4JDHWAQB0RPR6',
position: {
top: '10px',
left: '20px',
right: '20px',
bottom: '10px'
}
})
Open external URL in a new tab. Works on both web and mobile.
Preselect a meeting in the top meeting bar by Salesforce Meeting ID. From there, the user can easily start the meeting with a single click.
const objectFetchedFromSalesforce = {
// fetch dynamically from Salesforce or provide in another way
EventId: '00U1r00000D1J1zEAF',
}
ui.preselectSfdcMeetingId({ eventId: objectFetchedFromSalesforce.EventId }).then((response) => {
// e.g. display advanced meeting details inside your app
console.log(response.event)
})
Sends a query to the Pitcher Intelligent Assistant (PIA) and handles the streamed response.
// Subscribe to PIA's streamed responses
const cleanup = await useUi().on(
UI_MESSAGE_TYPES.UI_PROMPT_PIA_RESPONSE_STREAMED,
async ({ chunk, partial_response, id }) => {
console.log(`PIA response chunk for stream ${id}: ${chunk}`);
console.log(`PIA response so far for stream ${id}: ${partial_response}`);
}
);
// Prompt PIA with a question and ensure cleanup is called afterwards
useUi().promptPia({ prompt: "What's my most presented file?", id: 'my-prompt-id-to-discern-with-stream-event' })
.finally(cleanup);
Ask for a refreshed Salesforce token. In case the token hasn't expired yet, this method will return the same token as the current one found in the (getEnv
)[#getenv] result.
Optional
payload: RefreshServiceTokenRequestPromise resolving to an object containing the token
Renders a page from a file together with annotations.
Optional
documentId?: stringThe ID of the document to render (optional). If not provided the fileId will be used.
The ID of the file to render. Used when the documentId is not available.
The index of the page to render.
The parameters to use for rendering the page.
A promise that resolves with the image as an ArrayBuffer.
Resumes the meeting and attempts to go at the last presented route / component.
Opens the agenda selector modal to allow the user to select agenda content and handle the outcome.
const api = useApi() // or useUi() if you know that you 're in UI context
uiApi.selectAgendaContent({
// optional payload
initial_agenda: {
name: 'test',
groups: []
}
})
Allows the user to select (and preselect) canvases from the instance.
This method allows you to prompt the user to select canvases from the CatalogIQ instance and use that canvas selection in your application.
optional payload to preselect specific canvases
Promise with the user action and selected canvases
const api = useApi() // or useUi() if you know that you 're in UI context
api
.selectCanvases({
allowed_types: ['canvas','canvas-template','section','section-template'] // default ['canvas']
selections: [
{ id: "01HCZ623YYRFJQ0F7B69VWE510" },
{ id: "02HCZ623YYRFJQ0F7B69VWE510" },
], // default []
})
Opens the collection player selector modal to allow the user to select collection player content and handle the outcome.
const api = useApi() // or useUi() if you know that you 're in UI context
uiApi.selectCollectionContent({
// optional payload
initial_data: {
name: 'test',
groups: []
}
})
Allows the user to select (and preselect) content from the instance.
Opens the content selector dialog to allow the user to select content and handle the outcome. This method allows you to prompt the user to select content from the CatalogIQ instance and use that content in your application.
optional payload to preselect specific content
Promise with the user action and selected content
Dispatches iOS native file selector and returns the selected file.
Change the height of the postcall form.
Dispatches iOS only sync method for non-files.
Modify the currently loaded canvas. On the web it sends an update_canvas request to the server.
parts of the canvas object to update with fields to return
Updates canvas indicators by canvas ID. It merges the passed object into existing canvas indicators adding new keys if they were empty and overriding pre-existing keys.
Indicators can also be updated using updateCanvas API but in this case passed object fully replaces existing indicators.
// The fields param is appended to the URL as a query param.
onMounted(() => {
PitcherAPI.updateCanvasIndicators({
id: '01J9XT0WVXRTETF4CQZP42CPZP',
indicators: {
existing: { type: 'info', label: 'new label' }, // will be overriden
new: { type: 'info', label: 'INFO' }, // will be added
removeExisting: null // will be set to null and ignored, it is the same as removal
}
}).then((res) => {
console.log(res) // entire canvas object, including indicators field
})
})
Updates an existing folder.
The folder update payload, including the folder ID and update data.
A promise that resolves to the updated folder.
Navigate to another page in the CatalogIQ instance.
This method returns an object containing the API methods that are available to you in a given environment, whether that be the Canvas, UI, Admin or DSR.
usePitcherApi
anduseUi
useDsr
useAdmin