Create a New Entity

Overview

Follow these guidelines to create a new instance of an existing Entity type:

1. Create a new Entity.

2. Create additional Attributes for an entity (optional).

3. Create a new Constraint for an Entity (optional).

4. Create a User Interface (UI) Route (optional).

5. Create a UI Menu item from which to connect a UI Route to the Entity (optional).

Create a New Entity

Follow these steps to create a new Entity when creating a new instance of an existing Entity type:

1. View all Entity types. The Entities page displays.

2. Click the Create new Entity button. The Create new Entity page displays.

3. In the Name setting, enter the name for this Entity. Names may use underscore characters (_) but no spaces. This is a required setting.

4. In the Api Name setting, enter the name from which to refer to this Entity as a parameter when calling the ProcessMaker IDP API. Spaces are not allowed. As a best practice, use camel case. This is a required setting.

5. In the Pretty Name setting, enter the name of this Entity that displays in the side panel for files, folders, search results, most user interface components. Pretty names may use spaces. As a best practice, use a name users find meaningful.

6. In the Plural Name setting, enter how to refer to multiple instances of this Entity. For example, an Entity with the singular pretty name of person may be pluralized as people.

7. In the Query setting, enter what?.

8. Select the Enable Authorization checkbox to enable authorization for this Entity after creating the Entity. Do not select this option until after the Entity is created. This is a required setting.

9. Click the Save Entity button. The message Entity saved displays. The following occurs:

   • ProcessMaker IDP automatically creates the following Attributes:

     • ID references this newly created Entity.

     • CREATED_AT indicates the date this Entity was created.

     • CREATED_BY indicates which ProcessMaker IDP user created this Entity.

     • MODIFIED_AT indicates the date this Entity was modified.

     • MODIFIED_BY indicates which ProcessMaker IDP user last modified this Entity.

     As a best practice, do not rename these Attributes: be careful not to change the core schema unnecessarily.

   • The Created at setting displays the date this Entity was created. This is not editable.

   • The Created by setting displays which ProcessMaker IDP user created this Entity. This is not editable.

   • The Modified at setting displays the date this Entity was modified. This is not editable.

   • The Modified by setting displays which ProcessMaker IDP user last modified this Entity. This is not editable.

10. Optionally, create one or more additional Attributes for this Entity if necessary.

Create Additional Attributes for an Entity (Optional)

If additional Attributes for this Entity are not necessary, verify if one or more Constraints are required.

Follow these steps to create any additional Attributes for an Entity when creating a new instance of an existing Entity type:

1. Ensure you have created a new Entity to which this new Attribute applies.
2. Do one of the following depending on which page currently displays:

   • Editing the newly created Entity: After having clicked the Save Entity button when creating the new Entity, click the Attributes link from the left side bar. The automatically created Attributes for the new Entity display,.

   • Viewing ProcessMaker IDP Admin configurations: Click the Attributes link from the left sidebar. The Attributes page displays.

3. Click the Create new Attribute button. The Attributes page displays.

4. In the Name setting, enter the name for this Attribute. Names may use underscore characters (_) but no spaces. This is a required setting.

5. Do one of the following depending on from which page you began viewing Attributes for this procedure:

   • From the Edit Entity page: Skip to Step 6.

   • From the Attributes page: From the Entity Reference setting, select to which Entity this Attribute pertains. Follow these guidelines:

     1. Select the Entity to which this Attribute pertains. After selecting, the screen closes.

     2. Click the menu icon on the right side of the Entity Reference setting. This is a required setting. The Choose a reference screen displays.

6. From the Entity Reference setting, select to which Domain this Attribute pertains. This is a required setting. If a Domain does not yet exist, create one. Follow these guidelines:

   1. Click the menu icon on the right side of the Domain Reference setting. The Choose a reference screen displays.

   2. Select the Domain to which this Attribute pertains. After selecting, the screen closes.

7. In the Api Name setting, enter the name from which to refer to this Attribute as a parameter when calling the ProcessMaker IDP API. Spaces are not allowed. As a best practice, use camel case. This is a required setting.

8. In the Pretty Name setting, enter the name of this Attribute that displays in the side panel for files, folders, search results, most user interface components. Pretty names may use spaces. As a best practice, use a name users find meaningful.

9. In the Tab Order setting, enter the number in the sequential keyboard that this Attributes displays navigation order that this Attribute takes focus amongst other elements in the displayed content. Follow these guidelines:

   • Enter 0 for the first sequence in the keyboard navigation.

   • As a best practice, enter the sequence in increments of 10 so other Attributes may later be configured in the middle of this sequence.

10. From the Value Script setting, select the script to run that, when its outcome evaluates as TRUE, sets the value of this Attribute. If this setting has no script specified to run, then this Attribute's value is unchanged. Follow these guidelines:

    1. Click the menu icon on the right side of the Value Script setting. The Choose a reference screen displays.

    2. Select the script that may change the value of this Attribute. After selecting, the screen closes.

11. From the Required Script setting, enter the JavaScript to run that, when its outcome evaluates as TRUE, changes the current requirement status of this Attribute (required or not required). By default, this Attribute is not required. As a best practice, enter TRUE or FALSE into this setting to better manage data for this Attribute. Otherwise, the condition for requiring this Attribute's requirement may become problematic in different stages of processing documents that use this Attribute.

12. From the Visibility Script setting, enter the JavaScript to run that, when its outcome evaluates as TRUE, changes the current visibility state of this Attribute (visible or hidden). If the JavaScript evaluates as any result except TRUE, then the current visibility state of this Attribute is unchanged. By default, this Attribute is visible. As a best practice, enter TRUE or FALSE into this setting to better manage visibility for this Attribute. Otherwise, the condition for this Attribute's visibility may become problematic in different stages of processing documents that use this Attribute.

13. From the Read Only Script setting, enter the JavaScript to run that, when its outcome evaluates as TRUE, changes the current editable state of this Attribute (editable or read-only). If the JavaScript evaluates as any result except TRUE, then the current editable state of this Attribute is unchanged. By default, this Attribute is editable. As a best practice, enter TRUE or FALSE into this setting to better manage the editable state for this Attribute. Otherwise, the condition for this Attribute's editable state may become problematic in different stages of processing documents that use this Attribute.

14. From the Default Value Script setting, do one of the following:

    • Enter the JavaScript to run that, when its outcome evaluates as TRUE, changes this Attribute's default value. If the script evaluates as any result except TRUE, then this Attribute's current value is unchanged.

    • Enter a text string that becomes this Attribute's default value.

    By default, this Attribute has no value.

15. In the Tooltip Text setting, enter the text that displays information about this Attribute when mouse-hovering over the Help icon.

16. Click the Save Attribute button. The following read-only settings display information:

    • The Created at setting displays the date this Attribute was created.

    • The Created by setting displays which ProcessMaker IDP user created this Attribute.

    • The Modified at setting displays the date this Constraint was modified.

    • The Modified by setting displays which ProcessMaker IDP user last modified this Attribute.

17. Repeat Steps 3 through 13 for each Attribute required for this Entity.

18. Optionally, create a new Constraint for this Entity.

Create a New Constraint for an Entity (Optional)

If Constraints are not required for this Entity, verify if user interface Routes are required.

Follow these steps to create a new Constraint for an Entity when creating a new instance of an existing Entity type:

1. Ensure you have created a new Entity to which this new Constraint applies.
2. Do one of the following depending on which page currently displays:

   • Editing the Entity: After creating the new Entity or creating additional Attributes for that Entity, click the Constraints link from the left side bar.
   • Viewing ProcessMaker IDP Admin configurations: Click the Constraints link from the left sidebar. The Constraints page displays.

3. Click the Create new Constraint button. The Create new Constraint page displays.

4. In the Name setting, enter the name for this Constraint. Names may use underscore characters (_) but no spaces. This is a required setting.

5. From the Type setting, select which type of Constraint this is from the following options:

   • Foreign Key: A foreign key type Constraint establishes a relationship from children Entities to their parent Entity. Ensure to configure the Destination Entity Reference setting, below.

   • Index: An index type Constraint creates an index in the ProcessMaker IDP database.

   • Unique: A unique type Constraint ensures that an attribute, or a set of attributes, is unique. No duplicate file names are therefore allowed in the same folder.

   This is a required setting.

6. Do one of the following depending on from which page you began viewing Constraints for this procedure:

   • From the Edit Entity page: Skip to Step 7.

   • From the Constraints page: From the Entity Reference setting, select to which Entity this Constraint pertains. Follow these guidelines:

     1. Select the Entity to which this Constraint pertains. After selecting, the screen closes.

     2. Click the menu icon on the right side of the Entity Reference setting. This is a required setting. The Choose a reference screen displays.

7. In the Api Name setting, enter the name from which to refer to this Constraint as a parameter when calling the ProcessMaker IDP API. Spaces are not allowed. As a best practice, use camel case. This is a required setting.

8. In the Child Api Name setting, enter the name from which to refer from this child Constraint to a parent Constraint when calling the ProcessMaker IDP API. Spaces are not allowed. As a best practice, use camel case.

9. In the Child Pretty Name setting, enter the name of this child Constraint that displays in the side panel for files, folders, search results, most user interface components. Pretty names may use spaces. As a best practice, use a name users find meaningful.

10. Do one of the following:

    • Foreign Key option is not selected from the Type setting: Skip to Step 11.

    • Foreign Key option is selected from the Type setting: From the Destination Entity Reference setting, select to which Entity this Constraint applies. Follow these guidelines:

      1. Click the menu icon on the right side of the Entity Reference setting. This is a required setting. The Choose a reference screen displays.

      2. Select the Entity to which this Constraint pertains. After selecting, the screen closes.

11. In the Parent Pretty Name setting, enter the name of this parent Constraint that displays in the side panel for files, folders, search results, most user interface components. By default, a parent Constraint pertains to a Folder in your ProcessMaker IDP instance. Pretty names may use spaces. As a best practice, use a name users find meaningful.

12. Select the Inherit Authorization checkbox to do what?.

13. From the Cascade Type Delete drop-down menu, select from one of the following options:

    • Cascade: When a parent Entity instance is deleted, its children Entities instances are also deleted.

    • Restrict: A parent Entity instance cannot be deleted if it has children Entities instances.

    • Set Null: When a parent Entity instance is deleted, its children Entities instance references are set to NULL, in that they contain no values.

    Click the Delete icon to delete a selected option.

14. From the Cascade Type Update drop-down menu, select from one of the available options.

15. The Enabled option enables this Constraint. Do not select the Enabled option until after this Constraint is created.

16. From the Check Script setting, enter the required script.

17. Click the Save Constraint button. The following read-only settings display information:

    • The Created at setting displays the date this Constraint was created.

    • The Created by setting displays which ProcessMaker IDP user created this Constraint.

    • The Modified at setting displays the date this Constraint was modified.

    • The Modified by setting displays which ProcessMaker IDP user last modified this Constraint.

18. Repeat Steps 3 through 16 for each Constraint required for this Entity.

19. Optionally, create a UI Route for this Entity.

Create a UI Route (Optional)

A User Interface (UI) Route connects an Entity to a main navigation or Administrator navigation menu bar option, thereby triggering that Entity from the UI.

For example, if you access ProcessMaker IDP through client.doculayer.com and define a route /hr/employees for the Entity Employee, then you can access the Entity management page for employees through client.doculayer.com/hr/employees. For Entity types on the Admin navigation menu bar, the URL should start with /admin.

Follow these steps to create a new UI Route for an Entity when creating a new instance of an existing Entity type:

1. Ensure you have created a new Entity to which this new Constraint applies.
2. Edit the Entity that you created by doing one of the following:

   • Click the Entity from the Entities page.

   • Click the menu icon for that Entity, and then select Edit.

   The Edit Entity page displays with your Entity.

3. From the left side bar, click the Routes option. The Routes for Entity page displays.

4. Click the Create new UI Route button. The Create new UI Route page displays. The Entity Reference setting displays in read-only the name of this Entity to which this UI Route pertains.

5. In the URL setting, enter the URL from which this UI Route is accessed. This is a required setting.

6. Click the Save UI Route button. The following read-only settings display information:

   • The Created at setting displays the date this UI Route was created.

   • The Created by setting displays which ProcessMaker IDP user created this UI Route.

   • The Modified at setting displays the date this UI Route was modified.

   • The Modified by setting displays which ProcessMaker IDP user last modified this UI Route.

7. Optionally, create a UI Menu item from which to connect this UI Route to the Entity.

Create a UI Menu Item from Which to Connect a UI Route to the Entity (Optional)

Follow these steps to create a new UI Menu and at least one item from which to connect a UI Route with an Entity when creating a new instance of an existing Entity type:

1. Ensure the following:

   • You have created a new Entity to which this new UI Menu item connects.
   • You have created a UI Route that connects this Entity to the UI Menu item.
2. Click the UI Menus link from the left sidebar. The UI Menus page displays.

3. Click the Create new UI Menu button. The Create new UI Menu page displays.

4. In the Name setting, enter the name of this UI Menu. This is a required setting.

5. Click the Save UI Menu button. The following message displays: Ui Menu saved. The following read-only settings display information:

   • The Created at setting displays the date this UI Menu was created.

   • The Created by setting displays which ProcessMaker IDP user created this UI Menu.

   • The Modified at setting displays the date this UI Menu was modified.

   • The Modified by setting displays which ProcessMaker IDP user last modified this UI Menu.

6. Click the Items link in the left side bar. The Items for UI Menu page displays.

7. Click the Create new UI Menu Item button. The Create new UI Menu Item page displays. The Menu Reference setting displays in read-only the name of this Menu to which this UI Menu item pertains.

8. In the Order setting, enter the order in the UI Menu that this item displays in that Menu from top to bottom, beginning with 0. Lower numbers display higher in the list of Menu items.

9. In the Label setting, enter the label for this Menu item. This is a required setting.

10. In the URL setting, enter the same URL as configured for this Entity's UI Route, then suffix that URL for the path to this Menu item. To configure an external link, prefix the URL with http or https. This is a required setting.
11. From the Icon Reference setting, select the icon that displays beside this Menu item's label. This is a required setting for parent-level Menu items, but does not apply to child-level Menu items. Follow these guidelines:

    1. Click the menu icon on the right side of the Icon Reference setting. The Choose a reference screen displays.

    2. Select the icon that displays beside the Menu item's item. After selecting, the screen closes.

12. Click the Save UI Menu Item button. The following message displays: Ui Menu Item saved. The following read-only settings display information:

    • The UI Menu Item Reference displays what?.

    • The Created at setting displays the date this UI Menu item was created.

    • The Created by setting displays which ProcessMaker IDP user created this UI Menu item.

    • The Modified at setting displays the date this UI Menu item was modified.

    • The Modified by setting displays which ProcessMaker IDP user last modified this UI Menu item.

    • The ID setting displays the unique ID for this UI Menu item.

13. Optionally, create additional and/or child UI Menu items for this UI Menu. Create additional UI Menu items by clicking the Items link from the left side bar. From the Menu Reference setting, click the menu icon on the right side of the Menu Reference setting, and then select one of the following:

    • Add this new item to the general UI navigation: Select the NAV option to add this new item to the general navigation available to all ProcessMaker IDP users. Repeat Steps 8 through 13.

    • Add this new item to the Administrator UI navigation: Select the NAV_ADMIN option to add this new item to the navigation available only to ProcessMaker IDP Administrators. Repeat Steps 8 through 13.

Create a New Domain

Follow these steps to create a new Domain for an Entity when creating a new instance of an existing Entity type:

1. Ensure the following:

   • You have created a new Entity to which this new Domain applies.
   • You have created all Attributes that apply to this Entity.
   • You have created all Constraints that apply to this Entity.
2. Click the Domains link from the left sidebar. The Domains page displays.

3. Click the Create new Domain button. The Create new Domain page displays.

4. In the Name setting, enter the name for this Domain. This is a required setting.