Build your own Atlas CRM form
By using the API endpoints provided by Atlas CRM, a form can be build based on API template information and that form can then be used to create or even alter entities.
Last updated
By using the API endpoints provided by Atlas CRM, a form can be build based on API template information and that form can then be used to create or even alter entities.
Last updated
This article describes the process of building your own Atlas CRM form. Each of the following sections give a comprehensive description of the process for building such a form . First you will need to fetch the information necessary to base the form on. Then the form can be build making sure that the fields from a template are correctly translated to the right input field types. Finally, to create an entity, the form needs to make a call to the right endpoint with certain data send along.
Before a form can be build, first information is needed to base the form on. In Atlas CRM there are three main entities, companies, contacts and sales. Each entity-type has their own template. Templates define the information that can be stored in entities. A template consist of sections and fields. A section contains one or more fields. More about Templates.
Template information for a certain entity-type can be retrieved by calling the following endpoint. The endpoint retrieves a template based on a entity type. The fields retrieved by the template information endpoint have multiple property value pairs that say something about a field. The table below gives an overview of all properties a field can have.
Entry
Description
ID
Identifier of a field
Label
Name / label of a field.
Type
E.g. string, decimal, date, ect.
ISA
Extra information about a field type. For example a field of type decimal can be a currency or a percentage.
Read-only?
Read-only fields cannot be altered by users. This could be a calculated field like a timestamp of the moment an entity is created.
Required?
Required fields. For example an entity must always have a name.
Options
When the field is of type single-select, the options represent the possible selectable options.
Config
Extra field configuration parameters. (e.g. min=0, max=100)
For a API response sample, have a look at the API documentation for the template information endpoint. After template information is retrieved, it's time to build the form.
A form can be built in different ways, and in varying levels of complexity. This sections talks about the information templates contain, how it can be used to render a form, and what to look out for.
As you may already know, an Atlas CRM template is structured in multiple named sections containing one or more fields. So it would make sense to do the same in a form and displaying the fields in multiple sections. The fields that come with a template have a type. The type can be used to infer the form field input type.
The table below describes what types of form inputs work well with the different template field types. In what format and the data type of the values should be send to the API is discussed in the next section about calling the API to create an Atlas CRM entity.
Field-type
Description
String
single-line text input
user
single-line text input.
single-select
select input / dropdown list with just one selectable option. A field in a template of type single-select is always supplied with options.
text
textarea / multi-line text input
decimal
number input with support for decimal numbers.
date
date or datetime input.
Other than type, a field may provide other useful information that can be used to further configure a form field. Have a look at the example below.
These are two field of a template in JSON format with unnecessary information omitted like _links.
You can see that the isa value tells us that the field of type "decimal" and label "Estimated revenue" represents a currency. The config value tells us that the currency is in US Dollars. The second field, "Estimated probability" should represent percentages with a configuration set to have a minimal value of 0 and maximum of 100. This information can be used to show a dollar sign in front of the form field or a percentage sign after.
Lastly, some fields are read-only fields. These are fields that cannot be used when creating or editing entities. We suggest you to either show these fields as disabled form inputs or not showing them at all. Now that the form is build, it's time to create some entities.
This section is about sending data to the endpoint for creating an Atlas CRM entity. Sending the field values in the right data-type and format is precise and essential to make it run correctly. This section does not only apply to the endpoint discussed here, but it also applies to most other Atlas CRM endpoints.
To create the entity when submitting the form, the endpoint for creating an entity should be called. The endpoint expects a post request with certain body parameters. The format for the body parameters is shown below in JSON format.
The endpoint expects a different field-value data type to be sent depending on the field-type. Most of the field-values should be sent in text/String "string-value", but decimal type fields should be send as a decimal 55.5 (float/double) or number 21 (integer) data type.
For fields of type date the API expects a string/text value in a date and time format according to ISO 8601. The full format looks like YYYY-MM-DDThh:mm:ssTZD (e.g. 1997-07-16T19:20:30+01:00). Multiple parts of this format can be omitted like the seconds in the time. All possible formats can be read in detail at https://www.w3.org/TR/NOTE-datetime under the heading "Formats".
A few more things to be aware of when using the date and time format. When specifying time, be aware that omitting TZD (timezone offset) from the format, will default the timezone to UTC. For example Amsterdam should have a +02:00 timezone offset. Also, Atlas CRM does not store decimal fractions of a seconds, so always omit that from the time part of the format.
For fields that are of type user the API expects the given value to correspond with the Jira user key of a user. Supplying an incorrect user key will result in the an error saying: "user could not be found".
More about the endpoint for creating entities.
After making a valid or invalid call, the server will give a response. It will tell if the entity got created or not. You probably would like to show this response in some way to inform the user about what happened.
For invalid calls the server will give an error message saying what went wrong. The JSON format for the error differs depending on status code. More about that can be read in the API documentation.
After making a valid call, the server will respond with the just created entity.
When notifying the user and using the server response to display a message, the type of the created entity can be easily shown. The fields however, not so much. You probably want to show the label of the field with the field value. Not a unrecognizable field-ID. To solve this there are two approaches to map a field-ID to a field label. More on that further down this article at Mapping field-ID to field label.
You now know how to create a form that can create Atlas CRM entities. But there's more left to be explored.
For example, you can use the same form to alter existing Atlas CRM entities. You just have to call the following endpoint to find an existing entity. The fields with the values of the entity you get back need to be placed as values in the right form inputs. To do that you need to get the field-IDs of the template where you based your form on and the field-IDs from the existing entity you want to alter and match those IDs. Then after making changes to the entity in the form, you submit the form and call this endpoint to update the entity.
By calling this endpoint for retrieving multiple entities, a list of existing Atlas CRM entities can be constructed. The endpoint has support for filtering by entity type and pagination. This makes it possible to show a list of all sales and editing an existing sale by using what's described at the beginning of this section.
When fetching an existing Atlas CRM entity through the API you'll get the fields of an entity in the following form.
{"field-id": "value"}
The field-ID is an UUID (e.g. "cc7c9bd2-37de-4406-9a9d-78130b0caa48"). Going by field-ID alone, you can't really tell what field it is.
To be able to show a field in an application you'll probably want to show the field label. Or if you want to alter an existing entity you need to place the field values in the right form input.
If you've called the template endpoint earlier to create a form, you could use the template information from that call and match the field-IDs. Otherwise you can get the label of an field and other field information, by calling the field information endpoint. The endpoint is quite easy to use since it can find a field by field-ID alone. After looking up the field-ID, the label of that field can be used in the application.
