Categories & Custom Fields

Accelo is very extensible and supports numerous ways to customize your data. The three ways that are relevant to the Forms API are:

• Categories: these are "groups" and used for companies, contacts and affiliations to make database segmentation and categorization easier.

• Extension Fields: these are custom fields which are defined for Sales, Projects, Tickets and Retainers and are linked to a specific "Type" of those objects (so you can have different fields for a "Support" type ticket than you have on a "Customization" type ticket).

• Profile Fields: these are similar to extension fields, but a profile field is available across all types of an object (ie, all Tickets could have a Profile field for "Assigned Group" for example). Profile Fields are available on Companies, Contacts, Affiliations (the link between a Company and a Contact), Sales (aka Prospects), Projects (aka Jobs), Tickets (aka Issues) and Retainers (aka, Contracts).

You can use these custom fields in your forms using the formatting instructions below.

Categories in the Forms API

Categories are optional "groups" for company, contact and affiliation objects in Accelo.

To specify that you want to say that an object is in a category using the Forms API, you need to name the field category_object_IDENTIFER, where:

• OBJECT is one of:

  • company

  • contact

  • Affiliation

• IDENTIFIER is either:

  • The ID (an integer) of the Category; you can see the ID in the address bar when you click in to view a Category in the Configuration console.

  • The TITLE (a string) of the Category, such as Industry or Size.

Because categories work as a lookup, you need to make sure the "value" you pass in for this field is already an Option for the category in question. The "value" needs to match one of the options for your chosen category exactly.

Finally for Categories, you can send through more than one category of the same "name" but different values and Accelo will make sure the company, affiliation or contact is added to multiple lists (or have multiple entries of the same category but with different values).

Extension Fields in the Forms API

Extensions are custom fields on many objects in Accelo, including:

• Sales, also known as Prospects, and are created and modified on the "Custom Fields" tab for each Sale Type.

• Projects, also known as Jobs, are created and modified on the "Custom Fields" tab for each Project Type.

• Tickets, also known as Issues, and are created and modified on the "Custom Fields" tab for each Ticket Type.

• Retainers, also known as Contracts, and are created and modified on the "Custom Fields" tab for each Retainer Type.

To specify that you want to save a value into a profile field using the Forms API, you need to name the form field extension_OBJECT_IDENTIFIER, where:

• OBJECT is one of:

  • prospect

  • job

  • issue

  • contract

• IDENTIFIER can be either:

  • The ID (an integer) of the Extension; currently you can only see the ID by inspecting the DOM for the Custom Fields screen.

  • The TITLE (a string) of the Extension, such as "Department".

To ensure your database doesn't get polluted with lots of extensions you don't really want, the Extension Field need to exist in your Accelo database before they will be accepted/saved by the Forms API.

Similarly, the "value" you pass in through the API needs to match the type for the Extension field you've selected. Passing in "Someday" for a Date field won't work, for example; see below for how date values need to be formatted.

Profile Fields in the Forms API

Profiles are custom fields on many objects in Accelo, including:

• Companies, which are often used for tracking things like what Region the company belongs in, whether they're a VIP client, etc.

• Contacts, which are often used for tracking things like the name of a contact's spouse, their favorite sport team or other personal stuff which is consistent even if they change jobs.

• Affiliations, which are the links between a Contact and a Company, and are often used for tracking things like someone's Position or Responsibility in the company and which are relevant in the context of their job.

• Sales, also known as Prospects, and are sometimes used instead of Extension Fields for information you want to show on every sale type.

• Projects, also known as Jobs, and are sometimes used instead of Extension Fields for information you want to show on every project type.

• Tickets, also known as Issues, and are sometimes used instead of Extension Fields for information you want to show on every ticket type.

• Retainers, also known as Contracts, and are sometimes used instead of Extension Fields for information you want to show on every contract type.

To specify that you want to save a value into a profile field using the Forms API, you need to name the form field profile_OBJECT_IDENTIFIER, where:

• OBJECT is one of:

  • company

  • contact

  • affiliation

  • prospect

  • job

  • issue

  • contract

• IDENTIFIER can be either:

  • The ID (an integer) of the Profile; you can see the ID in the address bar when you click in to edit a Profile field in the Configuration console.

  • The TITLE (a string) of the Profile, such as VIP or Birthday.

To ensure your database doesn't get polluted with lots of profiles you don't really want, the Profiles need to exist in your Accelo database before they will be accepted/saved by the Forms API.

Similarly, the "value" you pass in through the API needs to match the type for the Profile field you've selected. Passing in "Someday" for a Date field won't work, for example; see below for how date values need to be formatted.

Finally for Profiles, you can send through more than one profile of the same "name" but different values and Accelo will process them as additional profiles.

Formatting Dates and Times

When you pass a date or datetime value into Accelo (through Extensions, Profiles or even built-in fields) you need to pass it across in the right format.

Date should be formatted as YYYY-MM-DD, eg a string of "2016-09-25".

DateTime values should be formatted as YYYY-MM-DD HH:MM:SS, eg a string of "2016-09-25 16:25:00" (note the use of 24 hour time). We don't currently support timezone in the values you pass; the timezone will be your "system wide" timezone, which you can configure from the "General Config > Settings" page of your Accelo account.