What is a Vocabulary?
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:
Process models and/or specific BPMN 2.0 elements in your Process models to ensure the JSON data model in Request data complies with the data structure outlined in the Vocabulary's JSON schema.
Screens to ensure that designers comply with the Vocabulary when they design Screens, and therefore validate that Request participants and Collection records also comply with the JSON schema's data structure.
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.
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.
Why Use Vocabularies?
ProcessMaker Platform uses a schema-less JSON data model from which to read, write, and store Request data. 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 Screen or variables a Script creates. When an in-progress Request routes through the Process, Request data aggregates into the JSON data model, thereby becoming Request data.
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
Video demonstration how to use a Vocabulary
How Do Vocabularies Work?
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.
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 Request summary. 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.
How Would I Use Vocabularies?
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:
Set Vocabulary permissions: Determine which users and/or groups have permission to view, create, edit or delete Vocabularies. See Vocabulary permissions.
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 related topics.
Configure which elements within a Process use a Vocabulary: After creating one or more Vocabularies, apply them to specific types of BPMN 2.0 elements and/or configuration within a Process. See the following topics:
Task elements