This article describes how to export files from Google Cloud Storage (GCS) and look up files and records on a per-record basis.
Start creating an export from Google Cloud Storage in either of the following ways:
-
From the Build menu, select Flows > Create flow. Then, click Add source.
-
From the Resources menu, select Exports. Then, click + Create export.
From the Application drop-down list, select Google Cloud Storage and your available Google Cloud Storage connection.
Name (required): Provide a clear and distinguishable name. You will have the option to choose this export throughout integrator.io, and a unique identifier will prove helpful later when selecting among a list of exports that you've created.
Description (optional): Describe your export so that you and others can quickly understand its purpose. Be sure to highlight any nuances that a user should be aware of before using this export in a flow. As you make changes to the resource, be sure to keep this description up to date.
Connection (required): The Google Cloud Storage connection to use for your export.
Parse files being transferred: Set to Yes if you want integrator.io to parse the file contents into structured records. If set to No, files are transferred as raw binary data without parsing.
File type (required): Choose the type of file to be exported from Google Cloud Storage. The file type you select changes the fields available in the export configuration. Acceptable file types include:
Sample file (that would be parsed) (required): This field only displays if you choose CSV, JSON, XLSX, or XML as a file type. Choose a sample file to define the record structure. Click Choose file and navigate to a sample version of the files you will be exporting.
CSV parser helper: The CSV parser helper can be used to visualize and experiment with how integrator.io parses CSV files (or any other delimited text files) into the JSON records/rows that then get processed by your flow. See CSV parser helper.
EDI x12 format (required): Select the EDI X12 file format that matches the files you are exporting.
EDIFACT format (required): Select the EDIFACT file format that matches the files you are exporting.
Format (required): Select the fixed width file format that matches the files you are exporting.
Sample file (that would be parsed) (required): This field only displays if you choose CSV, JSON, XLSX, or XML as a file type. Choose a sample file to define the record structure. Click Choose file and navigate to a sample version of the files you will be exporting.
Resource path: You can use this field optionally to define the JSON path to the resources you are exporting from the JSON file with handlebars syntax.
Sample file (that would be parsed) (required): This field only displays if you choose CSV, JSON, XLSX, or XML as a file type. Choose a sample file to define the record structure. Click Choose file and navigate to a sample version of the files you will be exporting.
File has header: Check this box if the files you are exporting contain a top level header row. If the first row of your XLSX file is reserved for column names (and not actual data), then check this box.
Sample file (that would be parsed) (required): This field only displays if you choose CSV, JSON, XLSX, or XML as a file type. Choose a sample file to define the record structure. Click Choose file and navigate to a sample version of the files you will be exporting.
XML parser helper: The XML parser will give you immediate feedback on how your parse options are applied against raw XML data. See XML parser helper.
Important
While creating an FTP XML import, remember that an unencrypted file size is limited to 250 MB and encrypted file size to 150 MB. During the import process, the file size can increase up to 500 MB.
Bucket name (required): Enter the name of the Google Cloud Storage bucket to export files from. You can also select a bucket from the drop-down list, which is populated from your connection's project. If the list cannot be retrieved, type the bucket name directly. You can use handlebars syntax to set the bucket name dynamically.
Directory path: Enter the path within the bucket to transfer only the files stored at that location. For example, if the full object path is my-bucket/reports/monthly/, enter reports/monthly/ as the directory path. If left blank, all objects in the bucket are eligible for transfer. Click Browse to navigate the bucket's virtual folder structure, or click the handlebars button to build a dynamic path. If you need to target a path that contains no objects yet, type it directly — empty paths do not appear in the Browse picker.
File filtering conditions: Add one or more conditions (or groups of conditions) to define the criteria used to determine which files are retrieved when the export runs. If no conditions are set, the export retrieves all files in the specified path. See Create file filtering conditions for FTP exports.
The Sorting and Grouping option allows you to manage your flow’s files by sorting and grouping records by field. This feature allows you to aggregate your data based on your chosen field(s), and sort the records in ascending or descending order (ASC or DESC).
This feature allows you to sort by multiple fields (ASC or DESC) or in the order that the fields were initially entered. You can enter the “Sort records by fields” by a field ID or by using a dot notation.
Note
-
This feature does not sort numeric fields, including dates, in descending or ascending values.
-
Sorting only applies to file provider exports. You can’t sort records for HTTP, database, and data warehouse exports or lookups at this time.
You can group records when parsing files from any file source, or when exporting records from HTTP, databases, or data warehouses. This feature allows you to aggregate your data based on your chosen field(s). Select the fields you want to group, based on your sample response data. Fields other than basic data types (such as string and number) are unavailable. If the source application does not sort the exported data, then grouping may not work as expected. The order of each grouping is always respected. You can enter records by field id, by using a dot notation, or one field at a time. When you input at least one field, the platform will group records in the order that the fields were initially entered, from top to bottom.
Note
The dot notation starts from “record”: { in the example below.
Take the following JSON record:
{
"page_of_records": [
{
"record": {
"NAME": "Sarah",
"AGE": 97,
"PURCHASE": "Beach towel",
"CATEGORY": "Summer"
}
},
{
"record": {
"NAME": "John",
"AGE": 98,
"PURCHASE": "Ski gloves",
"CATEGORY": "Winter"
}
},
{
"record": {
"NAME": "Ana",
"AGE": 99,
"PURCHASE": "Beach ball",
"CATEGORY": "Summer"
}
},
{
"record": {
"NAME": "James",
"AGE": 100,
"PURCHASE": "Snowboard",
"CATEGORY": "Winter"
}
}
]
}
Using the example JSON record, you can group by the Category field. Your data is grouped into Summer and Winter rows. Of course, integrator.io can handle more detailed groupings, say if you want to group records by Category and Purchase , or by Category , Age , and Purchase. If you’re working with a file provider export, you can sort the records by Ascending or Descending.
{
"page_of_records": [
{
"rows": [
{
"CATEGORY": "Summer",
"NAME": "Sarah",
"AGE": 97,
"PURCHASE": "Beach towel"
},
{
"CATEGORY": "Summer",
"NAME": "Ana",
"AGE": 98,
"PURCHASE": "Beach ball"
}
]
},
{
"rows": [
{
"CATEGORY": "Winter",
"NAME": "John",
"AGE": 99,
"PURCHASE": "Ski gloves"
},
{
"CATEGORY": "Winter",
"NAME": "James",
"AGE": 100,
"PURCHASE": "Snowboard"
}
]
}
]
}
In some cases, you might have CSV file exports or lookups:
|
Name |
Age |
Purchase |
Category |
|
Sara |
97 |
Beach towel |
Summer |
|
Anna |
98 |
Ski gloves |
Winter |
|
John |
99 |
Beach ball |
Summer |
|
James |
100 |
Snowboard |
Winter |
In this case, you’d group by column (Category), and each row would be grouped into the Summer or Winter category. Logically, it would look something like this:
|
Category |
Name |
Age |
Purchase |
|
Summer |
Sara |
97 |
Beach towel |
|
John |
99 |
Beach ball |
|
|
Winter |
James |
100 |
Snowboard |
|
Anna |
98 |
Ski gloves |
Tip
Remember that the Page size property under the Advanced section determines how many records/groups can go into a page. If a single group exceeds the page size, that group is discarded from the export, and an error indicating this issue is reported.
This matrix details all possible sorting and grouping outcomes.
|
Group records – not provided |
Group records – provided |
|
|
Sort records – not provided |
File processed as is. |
Content is grouped by group record fields. If a record has a missing field, then the record is grouped in a “missing fields” bucket. Noticegroup records by |
|
Sort records – provided |
Content is sorted by the created sort rules. |
Content is first sorted, then grouped. |
This section provides details regarding sorting and grouping new and existing flows.
When sorting and grouping files in a new lookup or export:
-
Select a Sorting and grouping option to specify the file transfer requirements.
Note
Deprecated grouping fields are not available when creating a flow.
-
Specify whether the file has headers.
-
Sort and group records as needed.
-
Select Save and close.
When editing sorting and grouping in a new flow:
-
Select a Sorting and grouping option to specify the file transfer requirements.
Note
Deprecated grouping fields are not available when creating a flow.
-
Specify whether the file has headers.
-
Sort and group records as desired.
-
Select Save and close.
When editing the sorting and grouping in an existing flow:
-
The deprecated fields are available until you start using the new feature.
-
Existing, deprecated group fields are automatically generated in the new feature, though they may require further configuration.
-
After the new fields are transferred and saved, the deprecated fields will disappear permanently. The only way to use the old fields is through the integrator.io API.
|
Setting |
Description |
|---|---|
|
Decrypt files |
This option is enabled if your connection is configured to use PGP encryption/decryption. When enabled, integrator.io decrypts files after downloading them from GCS. |
|
Decompress files |
Set to True if you are exporting compressed files. integrator.io decompresses the files after downloading them. |
|
Leave file on server |
When set to False, integrator.io deletes each file from the bucket after it is successfully transferred. Set to True to leave files in place after transfer. |
|
Backup bucket name |
Enter the name of the GCS bucket where integrator.io should archive a copy of the exported file. Leave blank to skip backup. If specified without a Backup file name, the original object name is preserved in the backup bucket. Supports handlebars syntax.
|
|
Backup file name |
Enter the full object name (path) for the backup copy, including any folder path. Supports handlebars syntax for dynamic naming. You must specify a Backup bucket name to use this field — a file name without a bucket is invalid and will prevent the export from saving. |
|
File encoding |
Select the character encoding for exported files. Defaults to UTF-8. Other supported values include Windows-1252 and UTF-16LE. |
|
Page size |
Enter the number of records to include in each page of export results. Defaults to 20. |
|
Data URI template |
Enter a template to construct a data URI for each exported file. Supports handlebars syntax. |
|
Override trace key template |
Enter a template to override the default trace key for exported records. Supports handlebars syntax. |
You can configure Google Cloud Storage as a file lookup in a flow to retrieve files on a per-record basis. The lookup form is identical to the export form described above. The only meaningful difference is that the lookup runs once per record rather than once per flow run, so the Bucket name, Directory path, and File filtering conditions fields typically reference data from the incoming record using handlebars syntax — for example, {{{record.orderId}}}.
If no matching file is found, the lookup follows the standard not-found behavior: fail, return empty, or skip, depending on how the lookup is configured.
To add a file lookup, click Add lookup in the flow builder, select Google Cloud Storage, and select Look up additional files (per record).
Note
When writing scripts or transforms that reference GCS file metadata, use fileMeta.name to identify the object — not fileMeta.key as you would for Amazon S3. File size is available as both fileMeta.fileSize and fileMeta.filesize.
You can configure Google Cloud Storage as a record lookup in a flow to retrieve object or bucket metadata on a per-record basis.
To add a record lookup, click Add lookup in the flow builder, select Google Cloud Storage, and select Look up additional records (per record).
Name (required): Provide a clear and distinguishable name.
Description (optional): Describe your lookup so that you and others can quickly understand its purpose.
Connection (required): The Google Cloud Storage connection to use for your lookup.
Resource (required): Select the GCS resource to look up. Accepted values:
-
Objects — retrieve metadata for individual GCS objects.
-
Buckets — retrieve metadata for GCS buckets.
API endpoint (required): Select the operation to perform. Available endpoints depend on the selected resource:
-
List objects (Objects) — returns a list of object metadata records from a bucket. Requires Bucket. Accepts an optional Directory path to scope the listing and an optional Max results to cap the number of records returned. GCS paginates automatically when Max results is blank. All fields support handlebars syntax.
-
Get object metadata (Objects) — returns metadata for a single object without downloading the file contents. Requires Bucket and Object name. Both fields support handlebars syntax.
-
Get bucket metadata (Buckets) — returns metadata for a single bucket, including location, storage class, versioning status, and labels. Requires Bucket. Supports handlebars syntax.
-
Click Save to save your current settings.
-
Click Save & close to save your changes and exit the page.
-
Click Close to exit without saving.