diff --git a/src/docs/version_001/docsStructure.ts b/src/docs/version_001/docsStructure.ts index 3f6c3f7..74057fb 100644 --- a/src/docs/version_001/docsStructure.ts +++ b/src/docs/version_001/docsStructure.ts @@ -152,6 +152,12 @@ export const versionOne: DocsStructure = { copy: 'copy.md', example: 'example.md', }, + { + title: 'Get Records by App', + folder: 'get_records_by_app', + copy: 'copy.md', + example: 'example.md', + }, ], }, { diff --git a/src/docs/version_001/resources/records/get_records_by_app/copy.md b/src/docs/version_001/resources/records/get_records_by_app/copy.md new file mode 100644 index 0000000..d60f8ad --- /dev/null +++ b/src/docs/version_001/resources/records/get_records_by_app/copy.md @@ -0,0 +1,99 @@ +# Get Records by App {% #get-records-by-app %} + +This endpoint returns an array of [records](#records) for a given app or survey. + +## Path Parameters + +{% table %} + +- Parameter Name +- Data Type +- Description + +--- + +- appId +- `number` +- The id of the app or survey that contains the records. + +{% /table %} + +## Query Parameters + +{% table %} + +- Parameter Name +- Data Type +- Description + +--- + +- fieldIds +- `string` +- A comma-separated list of field ids to include in the response. If not specified, all fields will be returned. + +--- + +- records +- `string` +- A comma-separated list of records ids to include in the response. If not specified, all records will be returned. + +--- + +- $filter +- `string` +- A [filter](#filter) expression that will be used to filter the records returned. + +--- + +- dataFormat +- `string` +- The [format](#record-data-format) of the field data in the response. Valid values are `Raw` and `Formatted`. If not specified, `Raw` will be used. + +{% /table %} + +## Filter {% #filter %} + +A filter expression is a string that is used to filter records returned. The filter operators available, the fields they are applicable to, and the syntax for each operator are described below. + +{% table %} + +- Operator +- Description +- Applicable Fields + +--- + +- eq +- Determines if the field equals a value. +- `Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`. + +--- + +- ne +- Determines if the field does not equal a value. +- `Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`. + +--- + +- lt +- Determines if the field is less than a value. +- `Number`, `date`, and `auto-number` fields and formula fields that have an output type of `number` or `date`. + +--- + +- gt +- Determines if the field is greater than a value. +- `Number`, `date`, and `auto-number` fields and formula fields that have an output type of `number` or `date`. + +--- + +{% /table %} + +### Delimiters + +When using a string value in a filter expression you must use single quotes (`'`) to delimit the string value. When using a date value in a filter expression you must use single quotes (`'`) to delimit the date value and the delimited value should be preceded by the word `datetime`. + +### Combining Filters + +You can combine multiple filters using the `and` and `or` operators as well as parentheses to control the order of operations. The `not` operator can be used to negate a filter. diff --git a/src/docs/version_001/resources/records/get_records_by_app/example.md b/src/docs/version_001/resources/records/get_records_by_app/example.md new file mode 100644 index 0000000..1a7ab0c --- /dev/null +++ b/src/docs/version_001/resources/records/get_records_by_app/example.md @@ -0,0 +1,77 @@ +# Retrieving records for an app + +{% code method="GET" heading="/Records/{appId}" defaultLanguage="bash" %} + +```bash +curl --location 'https://api.onspring.com/v1/Records/195?%24filter=not%20(6987%20lt%2010%20or%206986%20eq%20%27In%20Progress%27)%20and%206985%20gt%20datetime%272014-03-01T00%3A00%3A00.0000000%27&recordIds=5%2C100%2C101%2C102&fieldIds=6983%2C6986%2C6987%2C6985%2C6984&dataFormat=Formatted' \ +--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' +``` + +```csharp +using Onspring.API.SDK.Helpers; +using Onspring.API.SDK.Enums; + +var httpHelper = new HttpHelper( + config.baseUrl, + config.apiKey +); + +var appId = 195; +var filter = "not (6987 lt 10 or 6986 eq 'In Progress') and 6985 gt datetime'2014-03-01T00:00:00.0000000'"; +var recordIds = new[] {5, 100, 101, 102}; +var fieldIds = new[] {6983, 6986, 6987, 6985, 6984}; + +var records = httpHelper.GetAppRecords(appId, filter, recordIds, fieldIds, DataFormat.Formatted); + +foreach (var record in records) +{ + Console.WriteLine($"AppId: {record.AppId}, RecordId: {record.RecordId}"); + + foreach (var wrapper in record.Values.WithFieldId()) + { + Console.WriteLine($"FieldId: {wrapper.FieldId}, Type: {wrapper.Value.Type}"); + } +} +``` + +{% /code %} + +{% code heading="RESPONSE" defaultLanguage="json" %} + +```json +[ + { + "AppId": 195, + "RecordId": 5, + "FieldData": [ + { + "Type": 0, + "FieldId": 6983, + "Value": "Test Task 5" + }, + { + "Type": 0, + "FieldId": 6986, + "Value": "Complete" + }, + { + "Type": "Integer", + "FieldId": 6987, + "Value": 2 + }, + { + "Type": 0, + "FieldId": 6985, + "Value": "12/31/2021 6:00 AM" + }, + { + "Type": 0, + "FieldId": 6984, + "Value": "This is a test!" + } + ] + } +] +``` + +{% /code %} diff --git a/src/docs/version_002/resources/records/get_records_by_query/example.md b/src/docs/version_002/resources/records/get_records_by_query/example.md index 2cf88e0..bb74dca 100644 --- a/src/docs/version_002/resources/records/get_records_by_query/example.md +++ b/src/docs/version_002/resources/records/get_records_by_query/example.md @@ -104,7 +104,7 @@ value = '\'Test Task 5\'' request = QueryRecordsRequest( appId=195, filter=f'{fieldId} {operator} {value}', - fieldIds=[9686], + fieldIds=[6983, 6986, 6987, 6985, 6984], dataFormat=DataFormat.Formatted.name, )