Ange de företags- och/eller användarfält som appens användare behöver konfigurera när de aktiverar eller sparar appen.
Det som användaren fyller i fälten skickas med i varje anrop till din app.
Om du använder användarfält ser du till att alternativet ”User configurable” är aktivt för din app
Fältobjekt
Varje fält är ett objekt med följande egenskaper.
type (string)
Fälttypen. Scrolla ned till ”Fälttyper” för att se vilka alternativ som finns.
name (string)
Objektets namn. Det blir egenskapsnamnet i config-objektet som din integration tar emot.
entity (string)
Namnet på den entitet som fältet gäller. Giltiga värden är activity, agreement, appointment, account, contact, lead, order, orderrow, product, project, user, userDefined1, userDefined2, userDefined3, och userDefined4
Tillgängligt för fälttyperna: customfield, customfieldMultiple
description (string)
Beskriv vad användaren ska göra med fältet.
Tillgängligt för fälttyperna: Vanliga, Upsales
label (string)
Fältets etikett, det som användaren ser.
Tillgängligt för fälttyperna: alla
dependencies (array med fältnamn)
Fältet är dolt tills alla fält i listan har ett värde. Om du vill kräva ett visst värde skriver du "otherField==a,b": fältet visas när otherField har värdet a eller b. Om ett fält i listan använder externalValidation visas fältet när det fältet har klarat valideringen.
Tillgängligt för fälttyperna: alla
dependenciesAny (array med fältnamn)
Samma format som dependencies, men fältet visas när minst ett av fälten i listan matchar.
Tillgängligt för fälttyperna: alla
alwaysShowIfValue (true/false)
Om true visas fältet alltid när det har ett värde, även om dess beroenden inte är uppfyllda.
Tillgängligt för fälttyperna: alla
values (array med nyckel–värde-par)
Värdena som användaren kan välja mellan. Exempel:
[{"name": "whatTheUserWillSee", "value": "whatsSaved"}]
Tillgängligt för fälttyperna: Vanliga (Multi select, Select och Radio)
externalValidation (true/false)
Om fältet ska valideras mot din app. När det är true validerar din app konfigurationen.
När användaren skriver något i fältet gör vi ett anrop till din app på:
https://yourapp.com/testField/{field.name}
Anropet innehåller den information som användaren redan har fyllt i konfigurationen.
Om konfigurationen ska godkännas svarar du med statuskod 200.
Om konfigurationen inte ska godkännas svarar du med statuskod 400 och ett JSON-objekt med en beskrivning av felet, t.ex.
{ "error": "Your API key is not valid"}
Tillgängligt för fälttyperna: Vanliga, Upsales
externalValues (true/false)
Om fältets alternativ ska fyllas med värden från din app i stället för fördefinierade värden.
När användaren skriver något i fältet gör vi ett anrop till din app på
https://yourapp.com/fieldValues/{field.name}
Anropet innehåller all information som användaren redan har fyllt i konfigurationen. Svara med en array som innehåller de nyckel–värde-par som användaren ska välja mellan:
[{"name": "whatTheUserWillSee", "value": "whatsSaved"}]
Tillgängligt för fälttyperna: Vanliga (Multi select och Select)
required (true/false)
Om fältet är obligatoriskt eller inte. Om required är true och fältet är tomt kan användaren inte spara appens konfiguration med appen aktiv. Ett fält som är dolt på grund av sina beroenden är inte obligatoriskt.
Tillgängligt för fälttyperna: Vanliga, Upsales
Exempelobjekt
{"type": "header","name": "appHeader","title": "This is my header!","description": ""} {"name": "appCheckbox","type": "checkbox","label": "A checkbox to toggle","dependencies":[],"description": "Let's describe the checkbox a bit"} {"name": "textInput","type": "text","readonly": true,"label": "A simple text input","dependencies":[],"description": "Let's describe the checkbox a bit"} {"name": "orderStage","type": "upsalesOrderStageMultiple","required": false,"label": "Show the users order stages","dependencies":["appCheckbox"]}
Fälttyper
Designfält
Designfält används för att ge konfigurationen struktur.
header
markdown
En header inleder ett nytt avsnitt. Den tar title och description i stället för label, se exemplet ovan. Lägg till "size": "lg" för en större rubrik.
Ett markdown-fält visar texten i sin egenskap markdown, formaterad som Markdown.
Alla fält med "asHeader": true inleder också ett nytt avsnitt. På en checkbox visas då reglaget och etiketten i rubrikstorlek.
Vanliga fält
text
select
multiselect
checkbox
checkboxLarge
password
date
textarea
number
email
time
radio
button
För fälttyperna text och textarea finns en skrivskyddad funktion, se exemplet ovan.
Ett radio-fält visar sina values som en rad knappar, där användaren väljer en.
Ett button-fält visar en knapp med fältets label. När användaren klickar på den gör vi ett POST-anrop till din app på https://yourapp.com/configButton (https://yourapp.com/userConfigButton i en användarkonfiguration) med den konfiguration som användaren har fyllt i. config.buttonPressed innehåller knappfältets namn. Svara med ett JSON-objekt:
{ "valid": true, "message": "Connection works", "config": { "someField": "newValue" } }
message visas under knappen, i grönt om valid är true och annars i rött. Värden i config skrivs in i användarens konfiguration. Ange "saveBeforeClick": true för att spara konfigurationen innan anropet skickas; returnerade config-värden sparas då också. Ange "disabled": true för att visa knappen nedtonad, med disabledText som tooltip.
Upsales-fält
Upsales-fält är rullgardinsmenyer och flervalslistor med data från användarens Upsales-konto.
upsalesUser
upsalesRole
upsalesStage
upsalesOrderStage
upsalesOpportunityStage
upsalesActivityType
upsalesAppointmentType
upsalesCampaign
upsalesSegment
upsalesCompany
upsalesProduct
upsalesProductCategory
Alla Upsales-fält kan också användas som flervalslista, t.ex. upsalesUser och upsalesUserMultiple.
Egna fält
Egna fält är rullgardinsmenyer som fylls med de olika egna fält som finns i kundens databas. Om du vill använda dem anger du typen customfield (eller customfieldMultiple för en flervalslista) och entity till ett av de giltiga värden som beskrivs under rubriken Fältobjekt
Fältmappning
Fälttypen mapper låter användaren mappa fält mot ett externt system i appens konfiguration.
I en apps config-JSON anges fältet så här:
{
"fields": {
"account": [{
"name": "otherMappings",
"type": "mapper",
"label": "Other field mappings",
"dependencies": [],
"description": "Let's describe the mapper a bit",
"values": [{
"value": "field1",
"label": "Field 1",
"type": "upsales"
},
{
"value": "field2",
"label": "Field 2",
"type": "external"
}
]
}],
"user": []
},
"uiElements": {},
"requirements": []
}Där values är en array med möjliga värden i upsales-kolumnen och den externa kolumnen, som du väljer med fältet type.
Ytterligare två typer fyller upsales-kolumnen från användarens konto:
- {"type": "customfield", "entity": "account"} lägger till alla egna fält för den entiteten. Det sparade värdet är customfield_<entity>_<custom field id>, t.ex. customfield_account_12.
- {"type": "currency"} lägger till alla valutor i kontot. Det sparade värdet är currency_<ISO code>, t.ex. currency_EUR. Lägg till "skipMasterCurrency": true för att utesluta basvalutan.
Du kan också utelämna values-nyckeln och sätta externalValues till true. Då görs ett anrop vid inläsning mot /fieldValues/<name> i integrationen. Det förväntade svaret är en array med värden i samma format som ovan.
När värdet sparas i konfigurationen blir nyckelns värde en array med objekt med den här strukturen, där upsales är det valda Upsales-fältet och external är fältet i det externa systemet.
{
"upsales": {
"value": "field2",
"label": "Field 2",
"type": "upsales"
},
"external": {
"value": "efield2",
"label": "Other field 2",
"type": "external"
}
}
OAuth2
Om en app använder OAuth2-flödet för autentisering kan du ange ett fält så här:
{
"name": "auth",
"type": "oauth2",
"buttonLabel": "Sign in with Google",
"errorMessage": "Something went wrong",
"endpoint": "https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&scope=profile email&prompt=consent",
"clientId": "xyz-123",
"callbackUri": "https://yourapplocation/redirect",
"dependencies": [],
"required": true
}Om OAuth-leverantören är Google vill de att knappen följer deras stilguide. Det gör du genom att ange "brand": "google".
Fältvalidering:
Om appens konfiguration anger "test": true skickas ett anrop till /testConfig i din integration, med värdena i ett config-objekt i body, när användare sparar sina fältvärden. För användarinställningar anger du "userTest": true, och då går anropet till /testuserconfig.
Det kan användas för att validera användarens inmatning innan hen får spara appens konfiguration. Om endpointen inte svarar med 200 OK kan användaren inte spara sina värden.
EndpointPOST https://yourapp.com/testConfig
Body
Anropets body.data.config innehåller de värden som användaren har fyllt i.