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:: custom field

Available for field types: Regular fields, Upsales fields

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)

If the field depends that any other field already has input (or the field will be hidden).

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 and Select)

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 any 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. The user won't be able to save the app config if required is set to true and the field is empty.

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

Regular fields

text
select
multiselect
checkbox
checkboxLarge
password
date
textarea
number
email

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

Upsales fields

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

upsalesUser
upsalesRole
upsalesOrderStage
upsalesActivityType
upsalesAppointmentType
upsalesCampaign
upsalesSegment
upsalesCompany

Every Upsales field can also be used as multi select, e.g., user and userMultiple.

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 custom field 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.

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:

When users submit field values. A request is sent to /testconfig on your integration with the values in a config object on the body.

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.