Search Records

overview the search records action enables you to programmatically query records from swimlane applications within playbooks you can search using complex filter conditions, limit results, paginate through large result sets, and specify which fields to return the action uses the same filter builder functionality as building filters in records key benefits native action integrated directly into the playbook builder for streamlined workflow creation flexible filtering build complex search queries using multiple conditions and operators field selection return entire records or only specific fields to optimize data transfer pagination support handle large result sets with limit and page number options at least once execution ensures search results are retrieved even if the playbook is retried inputs the search records action requires the following inputs required inputs application select an application by either application id the unique identifier of the application application name the name of the application note you must provide either applicationid or applicationname , but not necessarily both filters filter conditions to apply to the search can be empty/no filters returns all records in the application (up to the limit) simple filters array of filter conditions complex filters nested clauses with and/or logic filter type how multiple filter conditions are combined and (default) all conditions must be true or at least one condition must be true optional inputs return fields specify which fields to return in the results all fields (default) returns complete record data specific fields returns only the selected field keys note if returnfields is empty or not specified, all fields are returned limit maximum number of records to return per page default 1000 records (if limit is 0 or not specified) maximum 1000 records minimum 1 record note the limit is clamped between 1 and 1000 if you need more records, use pagination page number 0 based page offset for pagination default 0 (first page) use with limit to paginate through large result sets deprecated the offset parameter is deprecated; use pagenumber instead date filter type optional date filter type for date field filters (minute, hour, day, week, month, quarter, year, alltime) filter operators the search records action supports the following filter operators equals field value exactly matches the specified value doesnotequal field value does not match the specified value contains field value contains the specified value (for strings) containsany field value contains any of the specified values excludes field value does not contain the specified value lessthan field value is less than the specified value lessthanorequal field value is less than or equal to the specified value greaterthan field value is greater than the specified value greaterthanorequal field value is greater than or equal to the specified value exists field exists (has a value) previous for date fields, matches previous period current for date fields, matches current period next for date fields, matches next period hour for date fields, matches specific hour dayofweek for date fields, matches specific day of week note available operators may vary depending on the field type (text, number, date, etc ) configuring the search records action step 1 select application from the inputs tab, select an application choose from the dropdown list of available applications, or use an expression to reference an application id or name dynamically step 2 configure filter conditions click add condition or use the condition builder to create filter conditions for each condition field click field to choose the field you want to filter on only fields available in the selected application are shown operator choose how the filter is evaluated using the operator dropdown available operators depend on the field type text fields equals, doesnotequal, contains, containsany, excludes, exists number fields equals, doesnotequal, lessthan, lessthanorequal, greaterthan, greaterthanorequal, exists date fields equals, doesnotequal, lessthan, lessthanorequal, greaterthan, greaterthanorequal, previous, current, next, hour, dayofweek, exists value enter or select the value to compare against the chosen field and operator you can use static values playbook properties from upstream actions playbook inputs expressions add multiple conditions add additional conditions to refine your filter filter type use the all/any (and/or) selector at the top all (and) all conditions must be true for a record to be included (default) any (or) at least one condition must be true for inclusion note if you don't add any filter conditions, all records in the application will be returned (up to the limit) step 3 configure return fields choose what data to return find entire records returns all fields of the matching records (default behavior if no fields are specified) return specific fields select specific fields to return only those field values, reducing data transfer and improving performance example if you only need the tracking id and status, select only those fields instead of returning all record data step 4 configure limit and pagination include limit enable/disable the limit on the number of records returned default 1000 records (if limit is 0 or not specified) maximum 1000 records minimum 1 record number of records set the maximum number of records per search result include page number enable/disable pagination for large result sets page number specify which page of results to return (0 based index) page 0 first page (records 1 to limit) page 1 second page (records limit+1 to 2 limit) and so on example to retrieve records 1001 2000 set limit to 1000 set page number to 1 step 5 apply changes click apply to save your configuration outputs the search records action provides the following outputs success output when the search completes successfully, the action returns result records an array of matching records each record is an object containing field key/value pairs if returnfields was specified, only those fields are included if returnfields was empty or not specified, all fields are included each record includes a tracking id field result count the total number of matching records (may be limited by iscountlimited ) result limit the limit that was applied to this search result result pagenumber the page number (0 based) that was requested result hasnextpage a boolean indicating whether there are more pages of results available result iscountlimited a boolean indicating whether the total count was limited for performance purposes example access search results in downstream actions error output if the search fails, the action returns error error information containing details about why the search failed common error scenarios application not found invalid filter syntax invalid field references permission errors invalid limit or page number values use cases example 1 search by tracking id scenario retrieve a specific record by its tracking id endpoint https //de1 swimlane app 443/api/account/{account id}/tenant/{tenant id}/app/{app id}/record/tracking/{tracking id} required parameters account id the unique identifier for the swimlane account tenant id the tenant associated with the account, representing the isolated environment within swimlane app id the application identifier where the record exists tracking id the unique tracking id of the record to retrieve example usage response example screenshot this screenshot shows the search record setup in swimlane, where you define the application name, filters (including the tracking id), and the fields to return search (with http action) the search (with http action) method allows users to perform a search directly through the swimlane api using an http get request this approach can be used to retrieve records based on specific criteria by providing the tracking id and other filter parameters http get endpoint https //de1 swimlane app 443/api/account/{account id}/tenant/{tenant id}/app/{app id}/record/tracking/{tracking id} authentication an api key or bearer token is required to authenticate the request include it in the request header as shown below request example response example screenshot this screenshot illustrates the configuration of the http action for get record in swimlane, using a direct http request to search by tracking id best practices use specific return fields when you only need certain fields, specify them in returnfields to reduce data transfer and improve performance set appropriate limits use limits to prevent retrieving too many records at once the default limit is 1000 records use pagination for large result sets if you need more than 1000 records, use pagination with pagenumber to retrieve additional pages optimize filter conditions use specific filters to narrow results before processing place the most selective filters first use exists operator to check for non null values handle empty results always check if result records is empty before processing use tracking ids from results store or use tracking ids from search results for downstream operations like updating or deleting records check hasnextpage when using pagination, always check hasnextpage to determine if more results are available consider performance avoid searching without filters on large applications use returnfields to limit data transfer use appropriate limits to balance between completeness and performance troubleshooting no records returned verify filter conditions are correct check that field values match exactly (case sensitive for text fields) ensure the application contains records matching your criteria review the count value to see total matches too many records add more specific filter conditions reduce the limit value use returnfields to reduce data size missing fields in results if you specified returnfields , ensure the field keys are correct check that fields exist in the application verify field keys match the application's field definitions pagination not working ensure pagenumber is 0 based (0 = first page, 1 = second page) check that limit is set appropriately verify hasnextpage to determine if more pages exist application not found verify the application id or name is correct ensure the application exists and is accessible check that application references are properly formatted filter errors verify filter syntax is correct ensure field ids/keys match application field definitions check that operator is appropriate for the field type validate that filter values match the expected data types performance issues add more specific filters to narrow results use returnfields to limit data transfer consider using smaller limits and pagination avoid searching without filters on very large applications