App API
De AppAPI stelt gebruikers in staat systeemmetagegevens te laden uit de app via verschillende methoden in de FormEngine en DMView. Het biedt toegang tot verschillende gegevenssleutels voor het ophalen van specifieke informatie uit de app.
In de XLSForm kunt u de functie pulldata() gebruiken met de volgende syntaxis:
'app-api': Dit sleutelwoord informeert de FormEngine om de gegevens te laden uit de App API.'data-key': Dit is de sleutel van de gegevens die u wilt laden uit de App API.- Als de gegevenssleutel ongeldig of niet ondersteund is, retourneert de berekening “n/a”.
Hier zijn de ondersteunde gegevenssleutels die u kunt gebruiken met de App-API:
osPlatform: Geeft de huidige OS-naam (Android of iOS) en de OS-versie terug. Webplatforms retourneren een lege waarde.
appPlatform: Geeft de naam van het app-platform terug, namelijk rtSurvey.
appVersion: Geeft de versienaam van de app terug.
getDisplayWidth: Geeft de schermbreedte van het apparaat in pixels terug.
getDisplayHeight: Geeft de schermhoogte van het apparaat in pixels terug.
getScreenSize: Geeft de schermgrootte van het apparaat in inches terug.
projectCode: Geeft de huidige projectcode van de site waarmee de gebruiker inlogt terug.
projectURL: Geeft de huidige project-URL van de site waarmee de gebruiker inlogt terug. De standaard/terugvalwaarde is een lege tekst ("").
startingPoint: Geeft het pad terug van het punt dat het formulier start. Raadpleeg de “Startpunt formulier” voor meer details.
serverTime: Geeft de beste beschikbare benadering van de datum en tijd op de server terug.
user.[attribuut]: Geeft de huidige gebruikersattributen terug op basis van de opgegeven attribuutsleutel. Raadpleeg de tabel “Gebruikersattributen” voor beschikbare attribuutsleutels.
Combineer de onderstaande attribuutsleutels met “user.” in de pulldata()-parameters om de huidige gebruikersinformatie op te halen. Gebruik bijvoorbeeld user.username, user.email, etc.
| Attribuutsleutel | Beschrijving |
|---|---|
| username | Gebruikersnaam van de gebruiker |
| name | Volledige naam van de gebruiker |
| staffCode | Personeelscode van de gebruiker |
| phone | Telefoonnummer van de gebruiker |
| E-mailadres van de gebruiker | |
| description | Beschrijvingstekst in gebruikersinformatie |
| organization_id | Organisatie-ID waartoe de gebruiker behoort |
| organization_name | Organisatienaam waartoe de gebruiker behoort |
| team_id | Team-ID waartoe de gebruiker behoort |
| supervisor_id | ID van de supervisor van de gebruiker |
| is_supervisor | 1 als de gebruiker een supervisor is, 0 indien niet |
instancePath: Geeft het pad van de huidige instantiemap terug.
appLanguage: Geeft de huidige apptaal terug die is ingesteld in de app-instellingen (bijv. vi, en).
openArgs.[attribuut]: Geeft het open-formulierargument terug dat is doorgegeven vanuit de ActionButton (act_fill_form, act_get_instance). De standaard/terugvalwaarde is een lege tekst ("").
primaryAppColor: Haalt de primaire kleur van de app op.
Gebruiksvoorbeelden
Sla de gebruikersnaam en organisatie van de enumerator op
| type | name | label | calculation |
|---|---|---|---|
| calculate | enumerator_name | pulldata('app-api', 'user.name') | |
| calculate | enumerator_org | pulldata('app-api', 'user.organization_name') | |
| calculate | enumerator_email | pulldata('app-api', 'user.email') |
Gebruik deze in notitatielabels voor auditdoeleinden:
note | interviewer_info | Interviewer: ${enumerator_name} (${enumerator_org})
Apparaat- en scherminfo
| type | name | label | calculation |
|---|---|---|---|
| calculate | device_platform | pulldata('app-api', 'osPlatform') | |
| calculate | app_ver | pulldata('app-api', 'appVersion') | |
| calculate | screen_w | pulldata('app-api', 'getDisplayWidth') |
Nuttig voor probleemoplossing: exporteer device_platform en app_ver samen met uw gegevens om te identificeren welke apparaatversie is gebruikt voor elke indiening.
Servertijd in plaats van apparaattijd
Apparaatklokken kunnen onjuist zijn. Gebruik serverTime voor een betrouwbaardere tijdstempel:
| type | name | label | calculation |
|---|---|---|---|
| calculate | server_ts | pulldata('app-api', 'serverTime') |
Voorwaardelijke logica op basis van gebruikersrol
Toon een sectie alleen voor supervisors:
| type | name | label | relevant |
|---|---|---|---|
| calculate | is_supervisor | pulldata('app-api', 'user.is_supervisor') | |
| begin_group | supervisor_section | Supervisorreview | ${is_supervisor} = '1' |
| text | supervisor_notes | Supervisornotities | |
| end_group |
Argumenten doorgeven vanuit een actieknop
Wanneer het formulier wordt gestart vanuit een act_fill_form-actieknop met aangepaste argumenten:
| type | name | label | calculation |
|---|---|---|---|
| calculate | passed_hh_id | pulldata('app-api', 'openArgs.household_id') | |
| calculate | passed_task | pulldata('app-api', 'openArgs.task_code') |
De actieknop moet de argumenten doorgeven met overeenkomende sleutels (bijv. household_id, task_code).
Projectinfo gebruiken
| type | name | label | calculation |
|---|---|---|---|
| calculate | project | pulldata('app-api', 'projectCode') | |
| calculate | project_url | pulldata('app-api', 'projectURL') |
Notities
- Alle
pulldata('app-api', ...)-aanroepen worden geëvalueerd wanneer het formulier wordt geopend en worden niet dynamisch opnieuw geëvalueerd tijdens de sessie (behalveserverTimeennow()). - Als een sleutel niet wordt ondersteund of als de gegevens niet beschikbaar zijn, geeft de functie
'n/a'terug (geen lege tekenreeks — test met!= 'n/a'in plaats van!= ''). openArgs-waarden zijn alleen beschikbaar wanneer het formulier wordt gestart vanuit een actieknop; ze retourneren anders een lege tekenreeks.