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, control the order in which records are returned, 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 explicit ordering sort records by tracking id in ascending or descending order to retrieve the oldest or newest matching records field selection return entire records or only specific fields to optimize data transfer pagination support use max records and page number to retrieve specific portions of an ordered result set 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 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 order configure how matching records are sorted before the record limit and pagination settings are applied sort by field records are currently sorted using the numeric portion of the tracking id only tracking id is supported sort direction ascending returns records from oldest to newest descending returns records from newest to oldest sorting by tracking id closely follows the record creation order for high volume applications or correlation heavy playbooks, prefer tracking id sort with pagination ( page number and max records ) instead of requesting very large result sets in a single run sorting by other fields, including last updated, is not currently supported 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 if returnfields is empty or not specified, all fields are returned max records maximum number of records to return per page default 1000 records (if max records is 0 or not specified) maximum 1000 records minimum 1 record the limit is clamped between 1 and 1000 if you need more records, use pagination with page number page number specify which page of the ordered result set to return default 1 page number works with max records to divide matching records into pages use a positive whole number important do not enter a negative page number example sort direction descending, page number 3 , max records 50 returns records 101–150 of the ordered result set 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, such as text, number, or date 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 do not 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 record order in the order section, configure how records are returned in sort by field , select tracking id select a sort direction ascending returns records from oldest to newest descending returns records from newest to oldest the action sorts records using the numeric portion of the tracking id this prevents values from being sorted as text and keeps the result order aligned with record creation time note new search records actions use descending as the default sort direction existing actions retain their current behavior unless you update their ordering configuration step 5 configure pagination configure the following options max records enter the maximum number of records to return per page default 1000 maximum 1000 minimum 1 max records is applied after the records are filtered and sorted page number enter the page of records to return default 1 use a positive whole number page number works with max records to determine the portion of the result set to retrieve example retrieve the latest 100 records configure the action as follows sort by field tracking id sort direction descending page number 1 max records 100 example retrieve the next 100 records configure the action as follows sort by field tracking id sort direction descending page number 2 max records 100 step 6 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 records in result records are returned in the configured tracking id order before the configured pagination and record limit are applied 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 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 retrieve the most recent records scenario retrieve the 100 most recently created records from an application configure the action as follows select the required application add any required filter conditions set sort by field to tracking id set sort direction to descending set page number to 1 set max records to 100 select the required return fields click apply example 2 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 max records 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 page number with max records to retrieve additional pages set the sort direction explicitly select ascending or descending whenever the record order affects downstream processing use descending for recent records use descending order with a low max records value to retrieve the latest matching records without over fetching use ascending for historical processing use ascending order when records must be processed from oldest to newest combine sorting and pagination carefully apply sorting before using max records or page number so that each request retrieves a stable portion of the result set avoid post processing where possible use the action's ordering controls instead of retrieving additional records and sorting them later in transform data or scripts tracking id sorting sorting is performed using the numeric portion of the tracking id rather than as a text value 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 max records 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 records are returned in an unexpected order verify that sort by field is set to tracking id verify that the required sort direction is selected use descending for newest to oldest results use ascending for oldest to newest results confirm that an existing action has been explicitly updated, because existing actions retain their previous behavior records are missing or repeated across requests verify the max records and page number values ensure the same filters and sort direction are used for each request do not change the sort direction between pagination requests avoid using negative page number values increment page number by 1 for each subsequent request while keeping max records constant sorting takes longer than expected add filter conditions to reduce the number of matching records use an appropriate max records value avoid querying all records in very large applications unless required sorting is currently limited to tracking id to reduce performance impact pagination not working ensure page number uses a positive whole number (default is 1) check that max records is set appropriately verify hasnextpage to determine if more pages exist use page number with max records only 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 max records values and pagination avoid searching without filters on very large applications