Article published on the 25th of May, 2023.
Relations is a way to relate one entity to another without them having an existing parent-child relationship.
An example could be a setup where you have a Companies module and a Contacts module, but where the Contacts module is not parented under the Companies module. Creating a relation between a company and a contact is possible using the Relations functionality. This relation makes it easy to find related contacts from a company site, or vise versa.
WorkPoint Automate has three steps which related to the Relations functionality:
- Relation form: Used to enter meta data of relations. Can be used to in processes to create new or edit existing relations.
- Create relations: An action step which creates relation(s) based on a relation form, or options configured directly on the step itself.
- Update relation(s): An action step used to update a relation, based on either a relation form, or options configured directly on the step itself.
In this article, we will demonstrate how to create processes for creating and editing relations, as well as how to view relations on entity sites.
2. Creating relations
Creating relations can be done in two ways: by first using a Relation form in which users can enter data for a relation and then using a Create relations step, or by simply using a Create relations step on which the relation data is configured directly on the step.
The former option is typically used if users should be able to create custom relations on the fly when working in the WorkPoint system.
The latter option is mainly used if a relation needs to be created but without the user needing to enter meta data and selecting a target entity, e.g., is the target entity is always known beforehand.
2.1. Creating relations using a form
If users should be able to enter data for relations and pick the target entity to relate to, a Relation form is required in the process. The simplest setup for achieving this is a Relation form step, followed by a Create relations step, as illustrated in the following image:
The Relation form does not need a step input, but we do need to select which entity is the source entity for the form. We can do this in the "Options" tab:
In this instance,we have made the Relation form generic such that it can be used on any entity on any business module (by selecting the current Business module- and Entity IDs from the process context).
Next, in the "Properties" tab, we can select a default start date for relations in the form, as well as a default responsible person. Additionally, we can select which business modules we can select target entities from:
Here we have selected a default start date using the adaptive expression "utcNow()", set the current user from the process context as the default responsible person, and a number of business modules from which users of the form can select an entity to relate to the source entity.
Next, we can feed the output of the Relation form into the step input of a Create relations step:
In the "Options" tab of the Create relations step, we need to define the source entity of the relation to create:
This should result in a process where we can enter meta data and select a target entity for one or more relations, and then create them:
2.2. Creating relations without a Relation form
If a static relation where all parameters are known beforehand should be created as part of a process, we can use the Create relations step without involving a Relation form.
Let's say that when we create a new project, the project should always be related to a specific company. Let's also say that the relation should always start on the current date, and the responsible person should be the person creating the project.
In this instance, we do not need to set a step input for the Create relations step, but we still need to define the source entity in the "Options" tab of the Create relations step:
Here, since we are in the process of creating a new project, the source entity is going to come from the "Projects" business module, and in the "Entity" field we select the ID of the project created by the "Create entity" step of the process.
Since we are not using a Relation form step to create data for the relation we want to create, we need to define the relation in the "Relations" tab:
Here we have created a relation which we have titled "WorkPoint relation". This title is only used to differentiate relations from one another in the Process Builder and is not displayed to users.
We have selected that the source relation type is "Project", and the target relation type is "Company". We have also used the "Business Module Id" and "Entity Id" fields to define which entity we want to relate the newly created project to.
We have set the Start date to "utcNow()", the Responsible to the current user, and the Description to ""WorkPoint is related to " + CreateEntity.Title + "."".
This process should allow us to create a new project, and have that project automatically be related to the entity on the "Companies" module with ID 2:
Note that if following the example in this section and using the "CreateEntity.ID" as source entity (in the "Options" tab of the Create relations step) for the relation, the Create entity step should utilize the "Synchronous" create site behaviour.
3. Editing relations
To edit relations, we need to create a WorkPoint Automate process which can display the current data of a relation, so that we can make edits to them. After that, the process needs to update the relation with the new edited data.
We can achieve this by using a Relation form, and the an Update relation(s) step - an example is shown in the following image:
In this instance, we need to somehow get the relation of a selected relation so that we can display it in the Relation form.
We can achieve this by setting the Step Input for the Relation form to "Selected items", as shown in the following image:
In the "Options" tab of the Relation form, we need to select the source entity for the form. We can make the process generic and usable across all business modules by selecting "BusinessModule.Id" and "Entity.ID" for the Business module and Business module entity fields:
Next, we can feed the output of the Relation form into the step input of a Update relation(s) step:
In the "Options" tab of the Update relation(s) step, we once again need to select the source entity for the relation. In this instance, we can use the same context options in the "Business Module" and "Entity" fields in the "Options" tab as we did on the Relation form:
When the process is saved and published, we need to set it as the "Default edit entity relation process" of each module on which we want to be able to edit relations using this process. For example, if we want to be able to use this process to edit relations from a specific project, we need to set this process as the Default edit entity relation process on the Projects business module.
We can do this from the General settings of the Projects business module:
In the image above, in the General settings for the Projects business module, we have selected the process to update relations.
Once this setting is saved for the business module, we can use a Relations webpart to display a given project's relations:
In the image above, we are currently on a site of a project titled "Project Blue" and on the "Relations" page, we are looking at a Relations webpart displaying a relation to the WorkPoint A/S company.
To edit this relation using the previously created Update relation(s) process, we can perform the steps in the following GIF: