File output tabular format extension contract reference

This required action writes the exported data to a specified destination and can be triggered from a Maestro workflow. The data is passed as a 2D array of strings, where each sub-array represents a row, and headers are provided as an array of strings.

Export To Destination is responsible for validating headers, setting headers if absent, and exporting the data to the destination. An example implementation could involve retrieving destination headers, comparing them with provided headers for data integrity, setting headers if the destination is blank, and then appending rows if headers match, returning a success or failure response. If headers do not match, an error is returned to prevent data corruption. The app manifest defines how Maestro recognizes and executes the exportToDestination action within a workflow, including the configuration details needed to authenticate and call the backend process that performs the export.

HTTP method

This action initiates a POST request to the external API service.

Request

{
  "destinationId": "abc123",
  "headers": ["Name”,”Email”,”Date"],
  "data": [
    [
       "John Doe”,”john@example.com”,”2024-10-24"],
       "Jane Smith”,”jane@example.com”,”2024-10-23"
    ]
  ]
}

Response

{
   "success": false,
   "errorMessage": “An error occurred while exporting the headers - too many requests.”
}

This required action contract is called by the configurator to verify that the selected destination can accommodate the data being exported. During this step, the system checks whether the destination sheet contains enough columns to match the number of variables provided. If the column counts don’t align, the configurator prompts the user to create a new destination or adjust the selected fields. When the destination has enough columns to hold all exported values, the configuration process is considered complete.

The List Headers action is part of the ExportTabularData extension contract.

When registering an extension app using an app manifest file, the action must be defined in the actions object. See Action schema for details about the required properties. The action definition must include these values, which are specific to this action:

• name: list-headers
• template: FileIO.Version1.ListHeaders

The value from actions.name (list-headers) is included in the extensions.actionReferences array.

Request

The request requires the unique identifier of the target destination.

{
    "destinationId": "abc_134"
}

Response

The response indicates whether the operation was successful and may return column headers for reference. Variables are written to existing columns in order rather than by name.

{
    "success": true,
    "headers": [“Name”,”Email”,”Date”,”Amount"],
    "errorMessage": null
}

This optional capability can be implemented for a file output tabular format extension. It returns a list of folders on the cloud storage system. If this capability is implemented, a workflow process builder can select from a list of folders when configuring a file output step or specify a naming convention for a new folder to be created.

Maestro can call List Directory Contents multiple times as a process builder configures a file output step, to enable the process builder to drill down in the folder structure. For example, the process builder can select Add Folder to choose a top-level folder. The process builder can then select Add Subfolder to choose a folder one level lower. Additional selections of Add Subfolder can be made to drill down further, and each time, a List Directory Contents request is executed.

List Directory Contents is the label that appears when you register an extension app using a guided, form-based process.

If you register your extension app using an app manifest file, make sure that you:

1. Include a definition for the capability in the actions object. See Action schema for details about the required properties. The action definition must include these values, which are specific to this capability:

   • name: list-directory-contents
   • template: FileIO.Version1.ListDirectoryContents

2. Include the value from the actions.name property in the extensions.actionReferences array.

3. Include the value from the actions.template property in the extensions.capabilities array.

See Extension schema for details about the actionReferences and capabilities arrays. See Example extension app use cases for a complete sample app manifest for file output to cloud storage.

HTTP method

This action initiates a POST request to the external API service.

Request

Request when List Directory Contents is called after after a process builder selects a drive (or similar container type) and then selects Add Folder:

{
  "filterOptions": {
    "entryType": "folder"
  },
  "parentId": "drive-id-1"
}

Response

{
  "parentId":"drive-id-1"
  "data":[
    {
      "type":"folder",
      "name":"Folder 1",
      "id":"folder-id-1",
      "parentId":"drive-id-1"
    },
    {
      "type":"folder",
      "name":"Folder 2",
      "id":"folder-id-2",
      "parentId":"drive-id-1"
    }
  ]
}

This optional capability can be implemented for a file output cloud storage extension. It returns the drives available in the cloud storage system. If this capability is implemented, a workflow process builder can select from a list of drives when configuring a file output step.

Note: If the cloud storage system does not have the concept of drives and instead organizes folders and files under a different container type, this capability can retrieve a list of those containers instead. They will appear in the file output step configuration pageʼs Select drive list.

List Drives is the label that appears when you register an extension app using a guided, form-based process.

If you register your extension app using an app manifest file, make sure that you:

1. Include a definition for the capability in the actions object. See Action schema for details about the required properties. The action definition must include these values, which are specific to this capability:

   • name: list-drives
   • template: FileIO.Version1.ListDrives

2. Include the value from the actions.name property in the extensions.actionReferences array.

3. Include the value from the actions.template property in the extensions.capabilities array.

See Extension schema for details about the actionReferences and capabilities arrays. See Example extension app use cases for a complete sample app manifest for file output to cloud storage.

HTTP method

This action initiates a POST request to the external API service.

Request

{
  "containerType": "drive",
  "parentId": ""
}

Response

{
  "containerType": "drive",
  "data": [
    {
      "containerId": "drive-id-1",
      "containerName": "Drive 1"
    },
    {
      "containerId": "drive-id-2",
      "containerName": "Drive 2"
    }
  ]
}