Learn how to maintain uniform JSON schemas for all ProcessMaker Platform assets in your organization.
Loading...
Manage uniform JSON schemas for all ProcessMaker Platform assets in your organization.
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Create a new Vocabulary that enforces JSON schema compliance in your ProcessMaker Platform assets.
The Vocabularies package must be installed.
Your user account or group membership must have the following permissions to create a Vocabulary unless your user account has the Make this user a Super Admin setting selected:
Vocabularies: Create Vocabularies
Vocabularies: View Vocabularies
See the Vocabularies permissions or ask your Administrator for assistance.
A Vocabulary is a JSON schema designed to validate ProcessMaker Platform assets to which that Vocabulary is applied. Any ProcessMaker Platform asset to which that Vocabulary is applied must conform to that JSON schema. Vocabularies are granular, in that one or more Vocabularies can be assigned to specific BPMN 2.0 element types within a Process or the Process model itself to validate the ProcessMaker Platform asset that is referenced from that element.
See Vocabulary Design Best Practices before you start designing a Vocabulary.
Follow these steps to create a new Vocabulary:
View your Vocabularies. The Vocabularies page displays.
In the Title field, enter the name of the Vocabulary. This name must be unique from all other Vocabularies. This is a required field.
In the Description field, enter the description of the Vocabulary. This is a required field.
Optionally, click the Browse button beside the JSON Schema field to locate the JSON schema from which ProcessMaker Platform assets are to conform. This file must use the .json
file extension. This setting is not required because you can design the Vocabulary after is it is created.
Click Save. The Edit page displays the Vocabulary. See Edit a Vocabulary.
Click the +Vocabulary button. The Create Vocabulary screen displays.
Delete a Vocabulary from being used in all ProcessMaker Platform assets in your organization.
The Vocabularies package must be installed.
Your user account or group membership must have the following permissions to delete a Vocabulary unless your user account has the Make this user a Super Admin setting selected:
Vocabularies: Delete Vocabularies
Vocabularies: View Vocabularies
See the Vocabularies permissions or ask your Administrator for assistance.
When a Vocabulary is deleted, ProcessMaker Platform assets that use that Vocabulary are not affected. However, that Vocabulary can no longer be used in other ProcessMaker Platform assets to maintain a uniform JSON schema.
Deleting a Vocabulary from the Vocabularies page cannot be undone.
Follow these steps to delete a Vocabulary:
View your Vocabularies. The Vocabularies page displays.
Click Confirm.
Edit the JSON data schema that a Vocabulary represents.
The Vocabularies package must be installed.
Your user account or group membership must have the following permissions to edit a Vocabulary unless your user account has the Make this user a Super Admin setting selected:
Vocabularies: Edit Vocabularies
Vocabularies: View Vocabularies
See the Vocabularies permissions or ask your Administrator for assistance.
Need to learn how to design JSON schemas? Start with JSON Schema. Need to learn how to convert valid JSON to a JSON schema? Use the JSON Schema Tool, though do not use JSON intended for production on this free GitHub application.
Follow these steps to edit a Vocabulary:
View your Vocabularies. The Vocabularies page displays.
Edit the following information about the Vocabulary as necessary:
In the Title field, edit the Vocabulary name. This is a required field.
In the Description field, edit the description of the Vocabulary. This is a required field.
In the Content section, edit the JSON schema following one or both of these methods:
Visually edit a Vocabulary using a graphical interface that non-developers may find easier to design a Vocabulary.
Changes made to the visual editor reflect in the coded JSON schema and vice versa.
Click Save.
Design a Vocabulary from the Visual tab in the Content section of a Vocabulary if you are not familiar with coding a JSON schema but understand the design compliance your ProcessMaker Platform assets must meet.
Changes to the Vocabulary in the Visual tab reflect in the Code tab, and vice versa.
Prior to editing the content of a Vocabulary, review the guidelines and best practices in Vocabulary design.
Follow these steps to visually edit a Vocabulary:
Select from the Length or Inherit column whether this Vocabulary inherits its properties, at least in part, from another Vocabulary. A property is a key-value pair to define an object in the JSON schema. If no other Vocabularies exist, only the No inheritance option is available. Note that unless a JSON schema was uploaded when this Vocabulary was created, its root name is mainSchema
. The JSON schema root contains the JSON schema properties as noted in the Property column. The default setting for the Length or Inherit column is No inheritance, meaning this Vocabulary does not reference properties from another Vocabulary.
Follow these guidelines to add a property to this Vocabulary regardless of whether this Vocabulary inherits the properties from another Vocabulary:
Click the + icon. A new property embeds to the JSON schema root and below any existing schema properties.
Rename this property by clicking inside the property name below the Property column.
Select which data type this property requires by selecting it below the Type column for this property. Specifying a data type for this property is not required; however, if a data type is not selected, then validation for that property's value does not occur. A JSON schema property may use one of the following data types:
Text (String
data type)
Integer
Decimal (Request data stores as a Floating Point
data type)
Boolean
Date (Request data stores a validated date as a String
data type if that date is acquired from a Date Picker control)
Datetime (Request data stores a validated datetime as a String
data type if that datetime is acquired from a Date Picker control)
Array
Object
See JSON Data Types for examples of each data type.
Indicate if this property requires a value by selecting the checkbox below the Required column for that property.
Do any of the following as necessary:
Select the Code tab to view your entire JSON schema.
Code a Vocabulary from the Code tab in the Content section of a Vocabulary.
Changes to the Vocabulary in the Code tab reflect in the Visual tab, and vice versa.
Prior to editing the content of a Vocabulary, review the guidelines and best practices in Vocabulary design.
Follow these steps to code a Vocabulary:
Edit your JSON schema. Optionally, select the Visual tab to view your entire JSON schema in the graphical interface.
Filter all Vocabularies in your organization to find that one you need.
Use the Search function to filter all Vocabularies from the Vocabularies page based on your entered text.
The Vocabularies package must be installed.
Your user account or group membership must have the "Vocabularies: View Vocabularies" permission to search for Vocabularies unless your user account has the Make this user a Super Admin setting selected.
See the Vocabularies permissions or ask your Administrator for assistance.
Follow these steps to search for a Vocabulary:
View your Vocabularies. The Vocabularies page displays.
Enter in the Search field the text to filter Vocabularies using any of the following criteria:
Name: Filter by the Vocabulary name that displays in the Title column.
Description: Filter by the Vocabulary description that displays in the Description column.
As you enter text into the Search field, Vocabularies display that match your entered text.
If there are no search results, the following message displays: No Data Available.
View the Vocabularies used to maintain uniform JSON schemas in your organization.
ProcessMaker displays all Vocabularies in one table. This makes it easy to manage Vocabularies.
The Vocabularies package must be installed.
Your user account or group membership must have the "Vocabularies: View Vocabularies" permission to view the list of Vocabularies unless your user account has the Make this user a Super Admin setting selected.
See the Vocabularies permissions or ask your Administrator for assistance.
Follow these steps to view all Vocabularies in your organization:
Ensure that you are logged on to ProcessMaker.
Click the Designer option from the top menu. The Processes page displays all active Processes.
The Vocabularies page displays the following information in tabular format about Vocabularies:
ID: The ID column displays the Vocabulary's ID. ProcessMaker Platform Platform automatically generates the ID value when the Vocabulary is created and represents a sequential number of how many total Vocabularies have been created to that time.
Title: The Title column displays the Vocabulary's name.
Description: The Description column displays the Vocabulary's description.
Modified: The Modified column displays the date and time the Vocabulary was last modified. The time zone setting to display the time is according to the ProcessMaker Platform instance unless your user profile's Time zone setting is specified.
Created: The Created column displays the date and time the Vocabulary was created. The time zone setting to display the time is according to the ProcessMaker Platform instance unless your user profile's Time zone setting is specified.
Use the Search field to filter Vocabularies that display.
Click the +Vocabulary button. See Create a New Vocabulary.
If no Vocabularies exist, the following message displays: No Data Available.
Control how tabular information displays, including how to sort columns or how many items display per page.
Follow best practices when designing Vocabularies.
Consider the following guidelines and best practices when designing Vocabularies:
Upload your JSON schema or design in ProcessMaker Platform: You may design your JSON schema before you create your Vocabulary or design it in ProcessMaker Platform. ProcessMaker Platform provides a graphical interface in the Visual tab of a Vocabulary that non-developers may find easier to design a Vocabulary. This may be helpful if you are not familiar with coding a JSON schema but understand the design compliance your ProcessMaker Platform assets must meet. If you are familiar with designing JSON schemas, you may code your JSON schema in the Code tab. Changes made in one tab reflect in the other tab.
Vocabularies designed in ProcessMaker Platform are named mainSchema
: If you design Vocabularies in ProcessMaker Platform instead of uploading one when a Vocabulary is created, the root name of the Vocabulary is mainSchema
. mainSchema
represents the top of the JSON schema object and contains the properties of that Vocabulary. If you upload your own JSON schema, its root name remains unchanged. JSON schema root names must begin with a letter, followed by any number of letters, integers (0
through 9
]), hyphens (-
), underscores (_
), colons (:
), or periods (.
).
Design your Vocabularies modularly: As a best practice, design your Vocabularies as segmented, minimal pieces rather than large encompassing JSON schemas. Small, modular Vocabularies can be re-used across multiple ProcessMaker Platform assets for a variety of Processes and business solutions. More specifically, Vocabularies can inherit their properties from other Vocabularies to build on one another, yet extend from those inherited Vocabularies.
Define properties in your Vocabularies in the order as intended: If you design your Vocabulary in the Visual tab, define its properties in the order from top to bottom as intended. Properties cannot be sorted in a different order than how you create them. However, you may view your Vocabulary in the Code tab, which displays the JSON schema as code, and then reorganize properties there.
Ensure the maximum length of each property is not 0
or a negative number: Except for the root of the JSON schema, such as mainSchema
, each property in a JSON schema and Vocabulary must have a length that validates how many digits, whether alphabetical, numeric, or alphanumeric, that validates conformity of data for that property. ProcessMaker Platform stores a property's length using the maxLength
key name by default to define the maximum number of digits that property's value may contain. For example, a person's age may contain no more than three (3) digits. Ensure that each property contains at least one (1) digit. To specify a minimum digit length of a property, select the Code tab and enter that minimum length using the minLength
key name. To specify an exact number of digits, use minLength
key name. For example, a credit card number must contain 16 digits.
Understand what a Vocabulary is in ProcessMaker Platform.
Use Vocabularies to ensure Request data complies with a specific data structure. This is often mandatory for many types of business sectors including banking and healthcare. Ensure the quality and compliance of Request data. For example, during a Loan Application process, ensure that personal information has been included in the Request to that moment in that in-progress Request.
See an example in the following video how to use a Vocabulary.
Intended audience: Process designers, software developers, and coding engineers
Viewing time: 15 minutes; contains narration
A Vocabulary is a JSON schema. The JSON schema describes the data objects, properties data types, and structure in both a machine- and human-readable format. Apply one or more Vocabularies to your ProcessMaker Platform assets including the following:
Complying with the Vocabulary's JSON schema ensures that you meet regulatory specifications and ensures that Request data and/or Collection records contains required information.
Each moment ProcessMaker evaluates workflow routing for an in-progress Request, ProcessMaker Platform also evaluates the Request data's conformity to the Vocabularies applied to the Process and/or a specific BPMN 2.0 element in the Process model. The Request's JSON data model must conform to the Vocabulary's JSON schema.
Vocabularies can be granular, in that they evaluate compliance only for specific objects in an in-progress Request's JSON data model. As a best practice, develop granular Vocabularies so that they can be re-used in multiple Processes and business sectors in your organization. Since you can add more than one Vocabulary to a Process or supporting BPMN 2.0 element, add as many smaller Vocabularies as necessary to target compliance. If you use Vocabularies that contain large JSON schemas, they will not be as re-usable to as many Processes.
Each Vocabulary is composed properties. A property is a key-value pair to define an object in the JSON schema.
Use Vocabularies throughout your organization in the following ways:
Event elements
Task elements
Click the Delete iconfor your Vocabulary. The Caution screen displays to confirm the deletion of the Vocabulary.
Click the Edit iconfor your Vocabulary.
The Edit page displays.
Locate the Content section of the Vocabulary below the Description setting. The Visual tab displays by default.
Click the View Property as Schema iconto view the JSON schema property as code.
Click the Delete Property iconto delete a property.
Locate the Content section of the Vocabulary below the Description setting, and then select the Code tab.
Click the Vocabularies icon from the left sidebar. The Vocabularies page displays all Vocabularies.
Click the Edit icon. See Edit a Vocabulary.
For example, a Purchase Request Process may require billing information as well as shipping information. These groups of information may be designed in segmented, separate modularly and then incorporated into a third Screen that uses controls to incorporate these segmented Screens for easier re-use and maintenance. Likewise, each of these Screens may use its own Vocabulary to validate required and conforming information for each. As a different design approach for this example, the Vocabulary that validates the shipping information may inherit the Vocabulary for the billing information, thereby referencing its JSON schema properties for easier maintenance; while referencing the Vocabulary for billing information, the Vocabulary for shipping information contains its own properties for validation and compliance.
Use the to ensure your Processes comply with specific data structures or regulatory specifications. Vocabularies apply to ProcessMaker Platform assets, including , , and .
The must be installed.
ProcessMaker Platform uses a schema-less JSON data model from which to read, write, and store . Since the JSON data model is schema-less (meaning that it does not require a specific schema or structure from which ProcessMaker Platform assets must conform), the JSON data model is structured from the JSON objects in assets used in a Request: the Variable Name setting values in a or variables a creates. When an in-progress Request routes through the Process, Request data aggregates into the JSON data model, thereby becoming Request data.
Process models and/or specific BPMN 2.0 elements in your Process models to ensure the JSON data model in complies with the data structure outlined in the Vocabulary's JSON schema.
to ensure that designers comply with the Vocabulary when they design Screens, and therefore validate that Request participants and records also comply with the JSON schema's data structure.
Need to learn how to design JSON schemas? Start with . Need to learn how to convert valid JSON to a JSON schema? Use the , though do not use JSON intended for production on this free GitHub application.
During an in-progress Request, if ProcessMaker Platform evaluates that the Request data no longer complies with all Vocabularies to that moment, the Request status changes from In Progress to Error. The error displays in the . Vocabularies are cumulative in an in-progress Request: as the Request progresses, if Request data does not conform with any Vocabulary's JSON schema to that moment in the Request, the Request errors.
Set Vocabulary permissions: Determine which users and/or groups have permission to view, create, edit or delete Vocabularies. See .
Manage your Vocabularies: Manage your organization's Vocabularies based on business sector, organizational department, or any way you want to maintain regulatory compliance in your ProcessMaker Platform assets. See .
Configure which elements within a Process use a Vocabulary: After one or more Vocabularies, apply them to specific types of BPMN 2.0 elements and/or configuration within a . See the following topics: