Configure a Collection

Access Collection Configuration Settings

Follow these steps to configure your Collection:

1. View your Collections. The Collections page displays.

2. Click the Configure icon for your Collection. The Configuration tab displays.

   

3. Refer to the following sections to configure your Collection. These configuration sections may be configured independently of one another:

   • Configure basic settings

   • Configure record permissions for users

   • Configure record permissions for groups

   • Configure columns of record attributes to display in the Collection view

   • Configure a relationship between data in a parent Collection with data in a child Collection

Configure Basic Settings

Follow these steps to configure basic settings for your Collection:

1. Access the Collection's settings. The Configuration tab displays. Use the Configuration tab to configure basic settings for your Collection.  

   

2. In the Name setting, edit the name of your Collection. Since this name displays in the left sidebar when the Collections top menu is selected, ensure that this is a descriptive name. This name is helpful for yourself and those with whom have access to this Collection. This is a required setting.

3. In the Description setting, edit the description of your Collection. This is a required setting.

4. From the Create Screen drop-down menu, select a Screen from which new records in this Collection are created. This must be a Form-type Screen. Optionally, select this setting's Open Screen option to view the currently selected Screen in a new browser window. This is a required setting.

5. From the Edit Screen drop-down menu, select a Screen from which to edit or update records in this Collection. This can be the same or a different Form-type Screen as selected from the Create Screen drop-down menu. Optionally, select this setting's Open Screen option to view the currently selected Screen in a new browser window. This is a required setting.

6. From the View Screen drop-down menu, select a different Screen from which to view records in this Collection. Use this Screen to only display all or parts of a record in the Collection. For example, the Screen selected from the View Screen drop-down menu may be designed to not display sensitive information that all Collection stakeholders should have access. This must be a Display-type Screen. Optionally, select this setting's Open Screen option to view the currently selected Screen in a new browser window. This is a required setting.

7. In the Custom Record Title setting, edit the text to display in the breadcrumbs menu when displaying a record from this Collection. This setting accepts mustache syntax to dynamically reference  Collection data that displays in record's breadcrumbs menu. All references included in mustache syntax for the custom record title are case sensitive. By default this setting has the value {{ id }} to reference the record ID of the Collection record that is currently displayed. Spacing within mustache syntax is not required, but provides greater readability. Reference Collection data by referencing the Collection variable in mustache syntax. Within the mustache syntax, precede the Collection variable name with data. to indicate that this is Collection data.  Example: {{ data.CollectionVariableName }} Include plain text in the Custom Record Title if this helps provide clarity to the record title. Custom Record Title data from a parent Collection is also displayed in a child Collection when viewing a record of that child Collection to highlight the relationship between the two Collections. Below is an example.   This is a record in the child Collection List of Courses in a College that has a relationship with the parent Collection List of Professors in a College. The name of the parent Collection and its Custom Record Title value, specified as: {{ data.professor_name }} - {{ data.professor_email }}

   appear above the record details of the child Collection record.

   

8. Enable the Use Randomly-Generated IDs for Links toggle key to generate random IDs for hyperlinks to records in this Collection instead of sequential numbering as each record is created. By default, each record in a Collection is numbered sequentially, which can potentially be determined to access a record without configured permission. This setting is disabled by default.

9. Optionally, configure if the Signals broadcast when record events in this Collection occur.

10. Click Save.

Configure Collection Signals for Subscription

Configure if the Signals broadcast for this Collection when any of the following record events occur. Each Collection's Signals are created and display in Signal Manager when that Collection is created.

• Record is created: When a record is created in this Collection, broadcast the Collection Signal for subscribing Signal-type events that listen for this event to occur. If this Collection Signal is disabled, it does not broadcast when this type of event occurs.

• Record is edited: When a record is edited in this Collection, broadcast the Collection Signal for subscribing Signal-type events that listen for this event to occur. If this Collection Signal is disabled, it does not broadcast when this type of event occurs.

• Record is deleted: When a record is deleted in this Collection, broadcast the Collection Signal for subscribing Signal-type events that listen for this event to occur. If this Collection Signal is disabled, it does not broadcast when this type of event occurs.

Follow these steps to configure your Collection's Signals for subscription:

1. Access the Collection's settings. The Configuration tab displays.

2. Locate the Collection Signals group of settings.

   

3. Configure the Collection's Signals for subscription following these guidelines:

   • Throw Signal on Insert: Toggle the Throw Signal on Insert toggle key to broadcast this Signal each time a record is created in this Collection. Note that if a comma-separated value (CSV) file is imported into this Collection to create records and the Throw Signal on Insert toggle key is enabled, that Signal broadcasts for each new record, possibly triggering that Signal's webhook if it is enabled. This toggle key is disabled by default.

   • Throw Signal on Update: Toggle the Throw Signal on Update toggle key to broadcast this Signal each time a record is edited in this Collection. Note that if multiple records from a Collection are edited in a batch, such as from a script, and the Throw Signal on Update toggle key is enabled, that Signal broadcasts for each edited record, possibly triggering that Signal's webhook if it is enabled. This toggle key is disabled by default.

   • Throw Signal on Delete: Toggle the Throw Signal on Delete toggle key to broadcast this Signal each time a record is deleted in this Collection. Note that if multiple records from a Collection are edited in a batch, such as from a script, and the Throw Signal on Delete toggle key is enabled, that Signal broadcasts for each deleted record, possibly triggering that Signal's webhook if it is enabled. This toggle key is disabled by default.

4. Click Save.

Configure Record Permissions for Users

Configure how users have permission to access the records in your Collection. Permissions may be set differently for each user or group. If a user account has the Make this user a Super Admin setting selected in that account, then these settings have no effect on that user. ProcessMaker does not check permissions for user accounts with this setting selected.

By default all users do not have any access to records in your Collection unless a user has the Make this use a Super Admin setting selected.

Follow these steps to configure how users have access to your Collection:

1. Access the Collection's settings. The Configuration tab displays.

2. Click the User Permissions tab.

   

3. Enter in the Search field the text to filter user accounts, if necessary.

4. Toggle any of the permission settings for applicable users to allow each user appropriate access to records in this Collection. By default all users do not have any access to records in your Collection unless a user has the Make this use a Super Admin setting selected. If necessary, ensure to grant your own user permissions to access records in your Collection. Follow these guidelines:

   • Create: Toggle the Create setting to grant or restrict permission for that user to create records in this Collection.

   • Delete: Toggle the Delete setting to grant or restrict permission for that user to delete records in this Collection.

   • Edit: Toggle the Edit setting to grant or restrict permission for that user to edit records in this Collection.

   • Edit Raw Data: Toggle the Edit Raw Data setting to grant or restrict permission for that user to edit JSON associated each record in this Collection.

   • View: Toggle the View setting to grant or restrict permission for that user to view individual records in this Collection.

   • List: Toggle the List setting to grant or restrict permission for that user to view the list of all records in this Collection.

5. Click Save.

Configure Record Permissions for Groups

Configure how groups have permission to access the records in your Collection. Permissions may be set differently for each user or group. Groups have access to records in this Collection under the following circumstances:

• Record-level permissions are cumulative: permissions set for a specific user apply regardless of whether that user is a member of a group with record permissions. If that user is granted permissions not granted to a group, regardless of whether that user is a group member, that user maintains that record permission.

• If a user has the Make this user a Super Admin setting selected in his or her user account, then these settings have no effect on that user. ProcessMaker Platform does not check permissions for user accounts with this setting selected. For more information about this setting, see Permission Description for Users and Groups.

By default all groups do not have any access to records in your Collection.

Follow these steps to configure how groups have access to your Collection:

1. Access the Collection's settings. The Configuration tab displays.

2. Click the Group Permissions tab.

   

3. Enter in the Search field the text to filter groups, if necessary.

4. Toggle any of the permission settings for applicable groups to allow its members appropriate access to records in this Collection. By default all groups do not have any access to records in your Collection unless a group member has this permission or has the Make this use a Super Admin setting selected for his or her user account. Follow these guidelines:

   • Create: Toggle the Create setting to grant or restrict permission for members of that group to create records in this Collection. If a group does not have the Create toggle key enabled, the +Record button used to create a record is not visible for its members unless individual users in the group have this permission.

   • Delete: Toggle the Delete setting to grant or restrict permission for members of that group to delete records in this Collection. If a group does not have the Delete toggle key enabled, the Delete iconused to delete each record is not available for members of this group unless individual users in the group have this permission.

   • Edit: Toggle the Edit setting to grant or restrict permission for members of that group to edit records in this Collection. If a group does not have the Edit toggle key enabled, the Edit iconused to edit that record is not available for members of this group unless individual users in the group have this permission.

   • Edit Raw Data: Toggle the Edit Raw Data setting to grant or restrict permission for members of that group to edit JSON associated each record in this Collection. If a group does not have the Edit Raw Data permission, JSON associated with a record of the Collection is not visible to members of this group unless individual users in the group have this permission.

   • View: Toggle the View setting to grant or restrict permission for members of that group to view individual records in this Collection. If a group does not have the View toggle key enabled, members of that group do not see any records in that Collection unless individual users in the group have this permission.

   • List: Toggle the List setting to grant or restrict permission for members of that group to view the list of all records in this Collection. However, if the View permission is enabled, then group members may view to individual records in this Collection.

5. Click Save.

Configure Columns of Record Attributes to Display in the Collection View

When a record in a Collection is viewed, the record data is displayed in tabular format with customizable columns.

Follow these steps to configure the columns to display when viewing records of your Collection:

1. Access the Collection's settings. The Configuration tab displays.

2. Click the Columns tab. Use the Columns tab to customize how the records in a Collection when viewed. Collection records display in tabular format when the View icon is clicked for a record. The Active Columns column displays the currently selected or default columns to present the Collection records in tabular format. The Available Columns column displays optional informational components that can be displayed.  

   

   The informational components in the Active Columns list display in the order that these informational components display in tabular format. Informational components at the top of the Active Columns column display left-most in the column order; components at the bottom of the Active Columns column display right-most in the column order.

3. Follow these guidelines to select which column(s) display information when viewing records in a Collection:  Remove a column that displays when viewing records in a Collection:

   1. From the Active Columns list, click the Remove iconfor the informational component not to display when viewing records in a Collection. The removed informational component moves to the bottom of the Available Columns list.

   2. Alternatively, drag the informational component from the Active Columns list to the Available Columns list.

   Add a column that displays when viewing records in a Collection:

   1. Drag the informational component from the Available Columns list to the Active Columns list, and then place the informational component in the order from top-to-bottom that you want that informational component to display when viewing records in a Collection. Informational components at the top of the Active Columns column display left-most in the column order; components at the bottom of the Active Columns column display right-most in the column order.

   Configure how a column displays information when viewing records in a Collection:

   1. Click the Configuration iconfor the informational component from the Available Columns column. Note that columns that do not have the Configuration icon are default columns that cannot be configured, but only removed from the Collection records view. The Configure screen for that informational component displays.

      

   2. In the Label setting, edit the column label that displays for the Collection record.

   3. In the Field setting, edit the variable name that represents the Collection variable used in the Create screen for this Collection. data. represents that what follows derives from a Collection variable. To derive that information, view the Collection variable used in that Collection's Create Screen, then use the specific key name in the following syntax, where CollectionData represents the variable name: data.CollectionData.

   4. Use the Sortable toggle key to adjust whether the column is sortable in search results.

   5. Click Save.

   Add a custom column to include custom labels when viewing the records in a Collection:

   1. Use the Add Custom Column screen to add custom labels for one of the default informational components, such as the Created By or Modified By columns, to provide more relevant context to that record information. Click the Add Custom Column button at the bottom of the Available Columns column. The Create Custom Column screen displays.

      

   2. In the Label setting, enter a column label that displays in search results.

   3. In the Field setting, enter the name of the default informational component replacing any spaces with an underscore. For example, for the Modified By column, set the Field setting to modified_by. This setting is case sensitive and all characters must be in lower case letters.

   4. Use the Sortable toggle key to adjust whether the column is sortable in search results.

   5. Click Save.

   Sort the order that columns display when viewing records in a Collection:

   1. Sort the informational components in the Active Columns list in the order that they are to display when viewing records in a Collection. To do so, click theicon for an informational component, drag it, and then place it into the order the column is to display. Do not drag the information component to the Available Columns column, or it will no longer be included as a column that displays when viewing records in a Collection.

   Reset the columns displayed when viewing records in a Collection:

   1. If it is necessary to reset the columns in your Collection to the default layout, click the Reset to Default button. Doing so displays the Reset to Default screen.

      

   2. Click Confirm.

   3. Click Save after you configure all your Collection settings.

Configure a Relationship Between Data in a Parent Collection with Data in a Child Collection

Configure a relationship between two Collections by designating one Collection as a parent Collection, the other as a child Collection, and defining data keys or columns linking both Collections. The Collection from which this relationship is created is automatically designated as the parent Collection. The relationship is a one-to-many relationship such that a record in the parent Collection can have multiple matching records in the child Collection.

Consider the following example of two Collections at a college:

• Professors: One Collection named Professors contains record information about each professor, such as the name, department of study, email address, and classes each professor teaches.

• Available Courses: Another Collection named Available Courses contains record information about all courses offered at that college, such as the name, the professor teaching that course, and its area of study.

The common data between these Collection records is the name of the course. Use this common data to establish a one-to-many relationship from one Collection to the other. To establish a relationship between the available courses and which classes are available of each course during a semester, the Available Courses Collection is the parent Collection. The Professors Collection is the child Collection that contains multiple records of each class from the Available Courses Collection, thereby establishing the one-to-many relationship between these Collections. Students use this example to register for classes in available courses.

Inversely, the Professors Collection can be the parent Collection, with the Available Courses Collection being the child Collection: students can view all classes that a specific professor teaches regardless of the courses that professor teaches.

Follow these steps to configure a relationship between data in your Collection with data in another:

1. Access the settings for the Collection to be the parent in the relationship. The Configuration tab displays.

2. Click the Relationships tab.  

   

3. Click the +Relationship button. The Add Relationship screen displays.

   

4. In the Name setting, enter a name for this relationship. This name displays when viewing a child Collection record in the Relationships tab of a record of the parent Collection. This is a required setting.

5. In the Description setting, enter a description for this relationship. This is a required setting.

6. In the Relationship section, configure details of this relationship by selecting a child Collection and the common data keys linking the child Collection to this parent Collection. The data in the parent Collection's key matches with that in the child Collection's key and the respective record(s) from the child Collection is retrieved. Follow these guidelines:

   1. From the Parent Collection Data Key drop-down menu, select a common data key from the parent Collection to link to its corresponding common data key in the child Collection.

   2. From the Child Collection drop-down menu, select the name of the child Collection to which to establish this relationship.

   3. From the Child Collection Reference to Parent Key drop-down menu, select the common data key from the child Collection to link to the selected data key in the parent Collection.

7. Click Save.