Specify the company and/or user fields your app needs its users to configure when activating or saving the app.

The information the user enters in the fields will be sent in every request to your app.

If you use user fields, make sure the option "User configurable" is active for your app

Field object

Each field is an object with the following properties available.

type (string)

The type of field. Scroll down to "Types of fields" to see available options..

name (string)

The name of this object. This will be the property name in the config object your integration receives.

entity (string)

The name of the entity that the field applies to. Valid values are activity, agreement, appointment, account, contact, lead, order, orderrow, product, project, user, userDefined1, userDefined2, userDefined3, and userDefined4

Available for field types: customfield, customfieldMultiple

description (string)

Describe what the user should do with the field.

Available for field types: Regular, Upsales

label (string)

The label for the field, what your user will see.

Available for field types: all

dependencies (Array of field names)

The field is hidden until every field in the list has a value. To require a specific value, write "otherField==a,b": the field is shown when otherField has the value a or b. If a listed field uses externalValidation, the field is shown once that field has passed validation.

Available for field types: all

dependenciesAny (Array of field names)

Same format as dependencies, but the field is shown when at least one of the listed fields matches.

Available for field types: all

alwaysShowIfValue (true/false)

If true, the field is shown whenever it has a value, even if its dependencies are not met.

Available for field types: all

values (array of key value pairs)

The values the user gets to select from. Example:

[{"name": "whatTheUserWillSee", "value": "whatsSaved"}]

Available for field types: Regular (Multi select, Select and Radio)

externalValidation (true/false)

If the field should validate against your app. With this set to true, your app will validate the configuration.

When the user enters someting in the field, we'll do a request to your app at:

https://yourapp.com/testField/{field.name}

The request contains information the user has already entered in the configuration.

If the configuration should validate, respond with status code 200.

If the configuration should not validate, respond with status code 400 and a JSON object containing a description of the error. e.g.,

{ "error": "Your API key is not valid"}

Available for field types: Regular, Upsales

externalValues (true/false)

If the fields options should be populated with values from your app instead of predefined values.

When the user enters someting in the field, we'll do a request to your app at

https://yourapp.com/fieldValues/{field.name}

The request contains any information the user has already entered in the configuration. Respond with an array containing the key value pair to select from:

[{"name": "whatTheUserWillSee", "value": "whatsSaved"}]

Available for field types: Regular (Multi select and Select)

required (true/false)

If the field is required or not. If required is set to true and the field is empty, the user can't save the app config with the app active. A field hidden by its dependencies is not required.

Available for field types: Regular, Upsales

Example objects

{
"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"]
}

Types of fields

Design fields

Design fields are used to give structure to your configuration.

header
markdown

A header starts a new section. It takes title and description instead of label, see the example above. Add "size": "lg" for a larger heading.

A markdown field shows the text in its markdown property, formatted as Markdown.

Any field with "asHeader": true also starts a new section. On a checkbox, the toggle and label are then shown in heading size.

Regular fields

text
select
multiselect
checkbox
checkboxLarge
password
date
textarea
number
email
time
radio
button

For field types text and textarea we offer a read-only functionality, see above example. 

A radio field shows its values as a row of buttons, of which the user picks one.

A button field shows a button with the field's label. When the user clicks it, we'll do a POST request to your app at https://yourapp.com/configButton (https://yourapp.com/userConfigButton in a user configuration) with the configuration the user has entered. config.buttonPressed holds the name of the button field. Respond with a JSON object:

{ "valid": true, "message": "Connection works", "config": { "someField": "newValue" } }

message is shown under the button, in green if valid is true and in red otherwise. Values in config are written into the user's configuration. Set "saveBeforeClick": true to save the configuration before the request is sent; returned config values are then saved as well. Set "disabled": true to show the button greyed out, with disabledText as its tooltip.

Upsales fields

Upsales fields are dropdowns and multi-selects with data from the users Upsales account.

upsalesUser
upsalesRole
upsalesStage
upsalesOrderStage
upsalesOpportunityStage
upsalesActivityType
upsalesAppointmentType
upsalesCampaign
upsalesSegment
upsalesCompany
upsalesProduct
upsalesProductCategory

Every Upsales field can also be used as multi select, e.g., upsalesUser and upsalesUserMultiple.

Custom fields

Custom fields are dropdowns which will be populated with the different custom fields that are available in the customer's database. To use them set the type to customfield (or customfieldMultiple for a multi-select) and entity to one of the valid values described under the headline Field object

Field Mapper

Field type mapper gives the user the option to map fields against an external system in the app config.

In the config JSON of an application the field is specified the following way:

{
 "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": []
}

Where values are an array of possible values in the upsales-column and external column by setting the type field.

Two more types fill the upsales-column from the user's account:

• {"type": "customfield", "entity": "account"} adds every custom field of that entity. The saved value is customfield_<entity>_<custom field id>, e.g. customfield_account_12.
• {"type": "currency"} adds every currency in the account. The saved value is currency_<ISO code>, e.g. currency_EUR. Add "skipMasterCurrency": true to leave out the master currency.

Alternatively, the values-key is omitted and externalValues is set to true. In that case, a request is made at load against /fieldValues/<name> on the integration. The expected response is an array of values in the same format as above.

When saved to the config the value of the key will be an array of objects with this structure. Where upsales is the selected upsales field and external is the field in the external system.

{
 "upsales": {
 "value": "field2",
 "label": "Field 2",
 "type": "upsales"
 },
 "external": {
 "value": "efield2",
 "label": "Other field 2",
 "type": "external"
 }
}

OAauth2

If an app uses the OAuth2 flow for authentication one can specify a field like the following:

{
    "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
}

If the OAuth provider is Google they want the button to follow their style guides, this can be achieved by specifying "brand": "google".

Field validation:

If your app config sets "test": true, a request is sent to /testConfig on your integration with the values in a config object on the body when users save their field values. For user settings, set "userTest": true and the request goes to /testuserconfig.

This can be used to validate user input before they are allowed to save their app config. If the endpoint does not respond with 200 OK the user will not be able to save their values.

Endpoint
POST https://yourapp.com/testConfig

Body
Request body.data.config contains the values the user has entered.