# 4. Data Debits ## PDA Data I/O: Reading (Data Debits) PDA `Data Debits` are the cornerstone of consented data exchange. It is the only way data can be retrieved from the PDA by anyone other than the owner and it enforces a strictly-defined format defining the specific data requested for the user to review and approve. Read more on the [Data Debit API](/build/dataswyft-one-apis/data-api/data-debits.md). ## Fetch Data Debits You can fetch the available `Data Debits` by using the next function: ```swift HATDataDebitsService.getAvailableDataDebits( userToken: userToken, userDomain: userDomain, succesfulCallBack: gotDataDebits, failCallBack: failedGettingDataDebits) ``` * `userToken` is the user's token to authenticate with the `PDA`. * `userDomain` is the user's `PDA address` needed to form the url to fetch the available `Data Debits`. * `succesfulCallBack` is a callback. This is called when the request is successful with a type of `@escaping (([DataDebitObject], String?) -> Void)`. The first parameter is an array of `DataDebitObject`. This is the structure of `Data Debits`. More on that in the next section. The second parameter is an optional `String`, the refreshed user token that the `PDA` returns. * `failCallBack` is a callback that is called when the request has failed. The type of the function is `@escaping ((Data PlugError) -> Void)`. `Data PlugError` is a custom object describing the errors that have occurred during the querying of the `Data Plugs`. A successful response will have `statusCode` 200 and look like this: ```javascript [ { "dataDebitKey": "97a0748f-bf81-4aaa-8f39-97ac2557d920", "dateCreated": "2018-01-02T15:22:42+0000", "permissions": [ { "dateCreated": "2018-01-02T15:22:42+0000", "purpose": "This Data Debit is in a legacy format, and the HAT App is unable to display all the information associated with it fully. This may include a logo, title and full description", "start": "2018-01-02T15:23:02.000Z", "period": 86400000, "cancelAtPeriodEnd": true, "termsUrl": "", "bundle": { "name": "97a0748f-bf81-4aaa-8f39-97ac2557d920", "bundle": { "iphone/locations": { "endpoints": [ { "endpoint": "iphone/locations", "mapping": { "accuracy": "accuracy", "latitude": "latitude", "longitude": "longitude", "timestamp": "timestamp", "lastUpdated": "lastUpdated", "locations.accuracy": "locations.accuracy", "locations.latitude": "locations.latitude", "locations.longitude": "locations.longitude", "locations.timestamp": "locations.timestamp" }, "filters": [] } ] }, "rumpel/locations/ios": { "endpoints": [ { "endpoint": "rumpel/locations/ios", "mapping": { "speed": "speed", "course": "course", "altitude": "altitude", "latitude": "latitude", "longitude": "longitude", "dateSynced": "dateSynced", "dateCreated": "dateCreated", "dateCreatedLocal": "dateCreatedLocal", "verticalAccuracy": "verticalAccuracy", "horizontalAccuracy": "horizontalAccuracy" }, "filters": [] } ] } } }, "accepted": false, "active": false, "end": "2018-01-03T15:23:02.000Z" } ], "requestClientName": "Data Exchange", "requestClientUrl": "https://dex.hubofallthings.com/", "requestClientLogoUrl": "https://dex.hubofallthings.com/assets//images/dex.png", "active": false, "accepted": false, "start": "2018-01-02T15:23:02.000Z", "end": "2018-01-03T15:23:02.000Z", "permissionsActive": null, "permissionsLatest": { "dateCreated": "2018-01-02T15:22:42+0000", "purpose": "This Data Debit is in a legacy format, and the HAT App is unable to display all the information associated with it fully. This may include a logo, title and full description", "start": "2018-01-02T15:23:02.000Z", "period": 86400000, "cancelAtPeriodEnd": true, "termsUrl": "", "bundle": { "name": "97a0748f-bf81-4aaa-8f39-97ac2557d920", "bundle": { "iphone/locations": { "endpoints": [ { "endpoint": "iphone/locations", "mapping": { "accuracy": "accuracy", "latitude": "latitude", "longitude": "longitude", "timestamp": "timestamp", "lastUpdated": "lastUpdated", "locations.accuracy": "locations.accuracy", "locations.latitude": "locations.latitude", "locations.longitude": "locations.longitude", "locations.timestamp": "locations.timestamp" }, "filters": [] } ] }, "rumpel/locations/ios": { "endpoints": [ { "endpoint": "rumpel/locations/ios", "mapping": { "speed": "speed", "course": "course", "altitude": "altitude", "latitude": "latitude", "longitude": "longitude", "dateSynced": "dateSynced", "dateCreated": "dateCreated", "dateCreatedLocal": "dateCreatedLocal", "verticalAccuracy": "verticalAccuracy", "horizontalAccuracy": "horizontalAccuracy" }, "filters": [] } ] } } }, "accepted": false, "active": false, "end": "2018-01-03T15:23:02.000Z" } } ] ``` * `dataDebitKey` is the data debit key, defined when creating the `Data Debit`. It's unique across the`PDA`. * `dateCreated` is the date that this `Data Debit` was created. The date is in `ISO` format as `String`. * `permissions` is the `permissions` info for this `Data Debit`. What `URLs` it has accessed, from which date to which date, etc.: 1. `dateCreated` is the date that this `Data Bundle` was created. The date is in `ISO` format as `String`. 2. `purpose` is a short description for the `Data Bundle` explaining its purpose. ***Optional*** 3. `start` is the start date that this `Data Bundle` has become active. The date is in `ISO` format. ***Optional*** 4. `end` is the start date that this `Data Bundle` will surpass the assigned duration stated in `period`. The date is in `ISO` format. ***Optional*** 5. `cancelAtPeriodEnd` is a flag indicating if the permissions will auto cancel when the `Data Debit` will end 6. `termsUrl` is a `URL` to show the user the terms and conditions for this `Data Bundle` 7. `period` is the duration that the `Data Bundle` can be active. Value in seconds. 8. `active` indicates if the `Data Bundle` is active 9. `accepted` indicated if the `Data Bundle` has been accepted 10. `bundle` is the part where the permissions are defined. Like what `endpoints` this `Data Debit` will have access to, which fields from that `endpoint`, a `name`, under what circumstances etc.: 1. `name` is name of the `bundle`. This has to be unique. 2. `bundle` is a `Dictionary` of type `Dictionary`, it allows definition of multiple different `endpoints` by giving a different name. This means that you can combine multiple and different `endpoints` each with its own requirements: 1. `endpoints` is an array of `DataOfferRequiredDataDefinitionBundleKeyEndpointsV2` containing the `PDA URLs` to include, a desired \`mapping\` or \`filtering\` for the fields: 1. `endpoint` the actual `endpoint` that you would like access to, for example `rumpel/profile` 2. `mapping` is the selected fields from this `endpoint` that you would like to have in the `Data Debit` 3. `filters` lets you filter a field by some requirements. For example, you can define something like `age` between 18 and 35. ***Optional***: 1. `field` is the field that you would like to apply filtering to 2. `transformation` is the transformation type to be done on the field. There are 4 different options: ***Optional*** 1. `identity` keep the value as-is, effect is the same as if transformation was not defined 2. `datetimeExtract` with `part` – extract part of a date from an ISO 8601 formatted date field 3. `timestampExtract` with `part` – extract part of a date from a UNIX timestamp date field 4. `searchable` convert the field to searchable text. Must be used together with the find operator below 3. `operator` is the type of the filtering. There are 4 different types with different structure each. You can read more into checking out `HATOperator` class in `HatForiOS` [here](https://github.com/dataswift/HatForIOS). ***Optional***: 1. `find` allows you to search a particular `String`, field name: `search`. Also, you can nest more `operators`, field name: `operator` 2. `contains` allows you to search if a particular substring is contained into a `String`, field name: `value` of type `Bool` 3. `between` allows you to search if an `Int` is between 2 values named `upper` and `lower` 4. `in` together with `value` field set to check if field is in (is contained by) `value` 4. `links` each `endpoint` can contain other `endpoint` objects. ***Optional*** 2. `orderBy` lets you define the field to order the data. ***Optional*** 3. `ordering` lets you define the `ordering` of the data. `ascending` or `descending`. ***Optional*** 4. `limit` is an `Int` which lets you define how many data points you like from this `endpoint`. ***Optional*** 11. `conditions` check `bundle` for the structure. The purpose is that the `Data Bundle` can have some conditions, that have to be fulfilled first, attached to it in order to become `active`. ***Optional*** * `requestClientName` is the name of the client that created this `Data Debit` * `requestClientUrl` is the `URL` to the website of the client * `requestClientLogoUrl` is a `URL` for the logo of the client * `requestDescription` is a description for the `Data Debit`. ***Optional*** * `requestApplicationId` If the `Data Debit` is tied to an `Application` this will be the application id. Otherwise it's nil. ***Optional*** * `active` indicates if the `Data Debit` is active * `accepted` indicates if the `Data Debit` has been accepted * `start` is the date that this `Data Debit` has started. The date is in `ISO` format as `String`. ***Optional*** * `end` is the date that this `Data Debit` will end. The date is in `ISO` format as `String`. ***Optional*** * `permissionsActive` Latest **active** `permissions`. Look at `permissions`. ***Optional*** * `permissionsLatest` Latest `permissions`. Look at `permissions`. A request that has failed will look like this: ```javascript { "error": "Not Authenticated", "message": "Not Authenticated" } ``` * `error` is the error that has occurred * `message` is a more descriptive message about the `error` that has occurred ## Create Data Debit You can also create a `Data Debit` by using the function below: ```swift let endpoint = DataOfferRequiredDataDefinitionBundleKeyEndpointsV2(endpoint: "rumpel/profile") let bundle = DataOfferRequiredDataDefinitionObjectV2( name: "test1", bundle: ["rumpel/profile": DataOfferRequiredDataDefinitionBundleKeyV2(endpoints: [endpoint])]) let dataDebitToCreate = DataDebitCreationObject( dataDebitKey: "test1", purpose: "none", start: "2018-11-14T23:51:40+0000", period: 432000000, termsUrl: "none", cancelAtPeriodEnd: false, requestClientName: "none", requestClientUrl: "none", requestClientLogoUrl: "none", bundle: bundle) ``` * `endpoint`is the `HAT endpoint` you would like access to. `DataOfferRequiredDataDefinitionBundleKeyEndpointsV2` also allows you to setup mapping and filtering if you wish. The minimum requirement is to specify the endpoint you want to use. * `bundle` is a grouping of different `endpoints` under one category. You can define one category, with the `name` parameter, but you can have multiple `endpoints` in the `bundle` section. Note that `name` has to be **unique**. * `dataDebitKey` is a key to the specific `Data debit`. This has to be **unique**. * `purpose` is a small description of the purpose for this `Data Debit` * `start` is the start date that this `Data Debit` can become available. The date is in `ISO` format. * `period` is the duration that the `Data Debit` will be active in seconds * `termsUrl` is the `URL` for the terms and conditions for this `Data Debit` * `cancelAtPeriodEnd` is a bool flag for if the `Data Debit` should be cancelled with the `period` passes * `requestClientName` is the name of the client that created this `Data Debit` * `requestClientUrl` is the `URL` to the website of the client * `requestClientLogoUrl` is a `URL` for the logo of the client * `bundle` is the description of what endpoints we want to have access to A successful response will have `statusCode` 201 and look like this: ```javascript { "dataDebitKey": "test1", "dateCreated": "2018-11-14T23:51:40+0000", "permissions": [ { "dateCreated": "2018-11-14T23:51:40+0000", "purpose": "none", "start": "2018-11-14T23:51:40+0000", "period": 432000000, "cancelAtPeriodEnd": false, "termsUrl": "none", "conditions": { "name": "data-debit-id-test-name", "bundle": { "test": { "endpoints": [ { "endpoint": "rumpel/profile" } ] } } }, "bundle": { "name": "data-debit-id-test1", "bundle": { "test": { "endpoints": [ { "endpoint": "rumpel/profile" } ] } } }, "accepted": false, "active": false, "end": null } ], "requestClientName": "none", "requestClientUrl": "none", "requestClientLogoUrl": "none", "requestDescription": "none", "active": false, "accepted": false, "start": "2018-04-18T09:26:57.000Z", "end": null, "permissionsActive": null, "permissionsLatest": { "dateCreated": "2018-11-14T23:51:40+0000", "purpose": "none", "start": "2018-11-14T23:51:40+0000", "period": 432000000, "cancelAtPeriodEnd": false, "termsUrl": "none", "conditions": { "name": "data-debit-id-test-name", "bundle": { "test": { "endpoints": [ { "endpoint": "rumpel/profile" } ] } } }, "bundle": { "name": "data-debit-id-test1", "bundle": { "test": { "endpoints": [ { "endpoint": "rumpel/profile" } ] } } }, "accepted": false, "active": false, "end": null } } ``` For an explanation of what the above structure means, read [here](/build/dataswyft-one-apis/data-api/data-debits.md). A failed request will look like this: ```javascript { "error": "Not Authenticated", "message": "Not Authenticated" } ``` * `error` is the error that has occurred * `message` is a more descriptive message about the `error` that has occurred ## Approve Data Debits Not all apps can directly approve `Data Debits`. This has to do with the permissions of the apps. Currently, only `HAT App` and web `Rumpel` can approve `Data Debits`. Due to the restrictions this guide will explain how to use the generic way of doing it, that will work on all apps. To approve a `Data Debit` you have to open the following URL in Safari: ```bash "https://\(hatAddress)/#/data-debit/\(dataDebitID)/quick-confirm?redirect=\(appScheme)://\(dataDebitHost)&fallback=\(appScheme)/dataDebitFailure" ``` * `hatAddress` is the (fully qualified domain) address of the PDA, e.g. `postman.hubat.net` * `dataDebitID` is the data debit id that you want to approve * `appScheme` is the URL where the user should be sent to after completing authentication. ***Optional***. For an `iOS`application that would probably be: `\(applicationName)://success` and has to be added in the `info.plist` file of the project in Xcode as a known URL. You can read more [here](/build/advanced-topics/pda-authentication/password-management/tutorials/ios-swift/1.-authentication.md#authentication-with-a-pda). * `dataDebitHost` is a string after the `://` part in the app url Scheme. For example `dataswift-sandbox://dataDebitHost`. With the`dataswift-sandbox://` `iOS` will launch your app. With the `dataDebitHost` you will know that this `URL` is specifically for the `Data Debits`. The process is the same as when logging the user in. Safari will open, user will have to complete their password, and then one of the 2 redirect `URL` will be called, depending if the request was successful or has failed for some reason. The app should know how to handle both scenarios. If you aren't sure how to do it you can read [here](/build/advanced-topics/pda-authentication/password-management/tutorials/android-kotlin/1.-authentication.md#step-1-redirect-user-to-pda-login) for how to redirect user to HAT login. ## Getting Data Debit values You can fetch the values of a specific `Data Debit` by using the next function: ```swift HATDataDebitsService.getDataDebitValues( dataDebitKey: dataDebitKey, userToken: userToken, userDomain: userDomain, succesfulCallBack: gotDataDebits, failCallBack: failedGettingDataDebits) ``` * `dataDebitKey` is the data debit key that we want the values from. * `userToken` is the user's token to authenticate with the `PDA`. * `userDomain` is the user's `PDA address` used to form the url to fetch the values of the `Data Debit`. * `succesfulCallBack` is a callback function that is called when the request is successful, with a type of `@escaping ((DataDebitValuesObject, String?) -> Void)`. This is the structure of `Data Debit Values`. More on that in the next section. The second parameter is an optional `String`, the refreshed user token that the `PDA` returns. * `failCallBack` is a callback that is called when the request has failed. The type of the function is `@escaping ((Data PlugError, String?) -> Void)`. `Data PlugError` is a custom object describing the errors that have occurred during the querying of the `Data Plugs`. The second parameter is the dataDebitKey. A successful response will have `statusCode` 200 and look like this: ```javascript { "bundle": { "profile": [ { "endpoint": "rumpel/profile", "recordId": "137e0409-effc-454f-b1f0-56fe87ad7762", "data": { "name": "", "nick": "", "photo_url": "https://postman.hubat.net/api/v2.6/files/content/rumpel1537454603415.jpg" } } ], "notables": [ { "endpoint": "rumpel/notablesv1", "recordId": "d1d26a7d-0c7f-4ba2-8caa-13a4b5671444", "data": { "kind": "note", "author": { "name": "", "phata": "postman.hubat.net", "nickname": "", "photo_url": "" }, "shared": true, "message": "oooo", "shared_on": [ "phata" ], "created_time": "2018-11-08T11:24:58Z", "updated_time": "2018-11-08T11:24:58Z" } } ] } } ``` Inside the `bundle` there are 2 different values: `profile` and `notables`. Those 2 values are `Arrays` that contain the actual data for each `endpoint` specified when this `Data Debit` was created. In this example the 2 structures are the `profile` and `notables`. A request that has failed will look like this: ```javascript { "error": "Not Authenticated", "message": "Not Authenticated" } ``` * `error` is the error that has occurred * `message` is a more descriptive message about the `error` that has occurred --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.dataswyft.com/build/advanced-topics/pda-authentication/password-management/tutorials/ios-swift/4.-data-debits.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.