ProcessMaker Query Language (PMQL) properties are the building blocks to search Request, Task, and Collection record information.
Use these ProcessMaker Query Language (PMQL) properties for Collection record PMQL search queries.
The following ProcessMaker Query Language (PMQL) properties apply to the Collection
data type to perform PMQL search queries from any of the pages accessible from the Collections sidebar icon in the Admin top menu option. PMQL search queries apply to records within the displayed Collection. Selecting any PMQL search result displays the Collection record for that result.
created
: Record's Creation Datecreated
property represents when the record was created from the currently displayed Collection.
Enter the datetime in the PMQL search query within quotation marks in the following format: YYYY-MM-DD HH:MM:SS
using 24-hour time. Example: "2020-07-01 14:25:15"
.
NOW
KeywordUse the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the interval unit of time is singular. PMQL supports the following units of time:
second
minute
Purpose of the search: Find Collection records created on or after March 14, 2020.
Purpose of the search: Find Collection records created one day ago for newly registered Freshmen students in which their academic interests include engineering-related majors except software engineering.
This example uses the data
object. The data
object stores the accumulated data from Screen controls used to create and edit records in its Collection by referencing the controls' Variable Name setting values.
A Select List control in which its Variable Name setting value is AcademicInterests
stores multiple options in a JSON object that each Freshman student selected as academic interests.
Note the following:
This example uses the AND
operator to require multiple property values for the search.
This example uses LIKE
operator with the %
wildcard to search for any Task name that includes the characters engineering
as an academic interest, but excludes those records with software
preceding any academic interest.
PMQL search queries are case sensitive. This example uses the lower
function to ensure all options from AcademicInterests
are evaluated regardless of their case sensitivity.
data
object: Search Collection Data for Specific Record InformationUse the data
JSON object to search for sought Collection records. The data
object stores the accumulated data from Screen controls used to create and edit records in its Collection by referencing the controls' Variable Name setting values.
All JSON objects and arrays within the JSON object named data
is the accumulation of data for each Collection. Each Request also stores its Request data in a data
JSON object. The key names for each JSON object or array derive from the Variable Name setting values in the Screens used for that Collection or any data injected into that Collection's JSON data model by Scripts or calls to the RESTful Application Program Interface (API).
Using the data
JSON object in PQML search queries helps answer the question "Which Collection records have specific information in them that I seek?" Use operators to compare the value for a particular Screen control to find records that only contain the value(s) you seek.
To determine what the Variable Name setting is for a control that stores Collection record information you seek, view the Screen that contains the control into which the sought data was entered and/or edited. Collections use as many as two Screens: one into which to enter data when a record in that Collection is created, and one from which record data is edited. The same Screen may be used for both purposes. Note that your user account or group membership must have the Screens: View Screens permission.
The data
JSON object precedes the Variable Name setting value, as noted above. Use JSON dot notation to reference sub-properties in the referenced Screen control if necessary.
Purpose of the search: Find Collection records in which Business majors have enrolled in at least 18 credits this semester.
When submitting which courses to enroll that semester, each student must enter the following information into a Screen that becomes data in that Collection record when that Screen is submitted:
A Select List control of which its Variable Name setting is Major
stores the JSON object value for the option that each student selects as a major.
A Line Input control of which its Variable Name setting is TotalCredits
stores as an integer the sum of all credits that the student selected for enrollment.
Note the following:
This example uses the AND
operator to require multiple property values for the search.
Purpose of the search: Find Collection records in which employment candidates had programming experience in at least JavaScript and Python and had "Manager" in a job title.
When submitting a job application, each candidate must enter the following information into a Screen that becomes data in that Collection record when that Screen is submitted:
A Select List control of which its Variable Name setting is CodingLanguages
stores the JSON object value of programming languages in which the employment candidate has experience.
A Loop control contains a Line Input control that stores the job title for each position the employment candidate held. The Variable Name setting values for each control are Jobs and JobTitle, respectively.
id
: Collection Record ID Numberid
property represents the ID number for the sought record(s) from the currently displayed Collection.
This id property only applies to Collection record-related PMQL search queries, and is distinct from the id
property for the Request
data type or for the id
property for the Task
data type.
Purpose of the search: Find Collection records that are newer than record ID 7.
Purpose of the search: Find Collection records newer than Task ID 7 that were created after March 14, 2020.
Note the following:
This example uses the AND
operator to require multiple property values for the search.
This example uses the created
property to search for which Collections were created by a particular date. Note that PMQL interprets strings in the format YYYY-MM-DD HH:MM:SS
as dates and can be used in comparative queries if that string is in quotation marks ("2020-03-14 00:00:00"
).
modified
: Datetime Record Last Modifiedmodified
property represents when the record was last modified from the currently displayed Collection. A record modifies when the contents of the a record changes from any of the following:
A record is manually changed by a user that has permission to edit records in that record's Collection.
A Script adds or modifies data in a record.
A record is modified via the RESTful API.
Enter the datetime in the PMQL search query within quotation marks in the following format: YYYY-MM-DD HH:MM:SS
using 24-hour time. Example: "2020-07-01 14:25:15"
.
NOW
KeywordUse the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the interval unit of time is singular. PMQL supports the following units of time:
second
minute
Purpose of the search: Find Collection records modified less than 30 minutes ago.
Note that this example uses the NOW
keyword to represent the current datetime, and then uses the Less Than operator (<
) to determine the datetime 30 minutes ago that the applicable Collection records were modified. Note that the unit of chronological measurement (minute
) is singular.
Purpose of the search: Find Collection records modified one day ago associated with students whose graduation year is 2022 and who last met their advisor more than six months ago.
This example uses the data
object. The data
object stores the accumulated data from Screen controls used to create and edit records in its Collection by referencing the controls' Variable Name setting values. The following Screen controls store data that this PMQL search query references:
GraduationYear: The GraduationYear
control stores at which year a student graduates. This value is stored as a string.
AdvisorMeetingDate: The AdvisorMeetingDate
control stores at which date a student met with her or his advisor.
Note the following:
This example uses the AND
operator to require multiple property values for the search.
This example uses the CAST
function to convert the string to a number for comparison in the PMQL search.
Use these ProcessMaker Query Language (PMQL) properties for Request PMQL search queries.
The following ProcessMaker Query Language (PMQL) properties apply to the Request
data type to perform PMQL search queries from any of the pages accessible from the Requests top menu option. Selecting any PMQL search result displays the Request summary for that result.
completed
: Request's Completion Datetimecompleted
property represents when the Request completes.
Enter the datetime in the PMQL search query within quotation marks in the following format: YYYY-MM-DD HH:MM:SS
using 24-hour time. Example: "2020-07-01 14:25:15"
.
NOW
KeywordUse the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the interval unit of time is singular. PMQL supports the following units of time:
second
minute
hour
day
See Example 2 how this property can apply to Service Level Agreement (SLA) contract compliance.
Purpose of the search: Find completed Requests for the Purchase Request Process between February 3, 2020, and February 10, 2020.
This example uses the AND
operator to search for multiple required property values.
This example uses the request
property. The request
property value ("Purchase Request Process"
) is not case-sensitive.
Purpose of the search: Find completed Requests for the "SLA for Purchase Request Process" that started on or after March 1, 2020, but did not complete on or prior to March 4, 2020, for purchase orders submitted through the New York or Chicago branches that are at least $10 million.
This example uses the data
object that represents Request data. The following Request variables store Request data that this PMQL search query references:
Branch: The Branch
Request variable stores to which company branch office a purchase request was submitted. Different branch offices might have different Service Level Agreement (SLA) contract requirements for which they must comply. For example, the New York and Chicago offices must complete a purchase request within three (3) days; the Charlotte office must complete requests within five (5) days.
TotalCost: The TotalCost
Request variable stores the total amount for the purchase request.
This example uses the OR
operator to search for any of multiple properties within an AND
operator to find those Requests associated with either the New York or Chicago branches.
Use a PMQL search query similar to this example to monitor which Requests completed past the sanctioned time period a SLA contract allows. In this example, if a Request completes three (3) days or later from when it starts for high-profile purchase requests and/or for flagship offices, then a company executive can apologize to the client for the late service delivery.
created
: Request's Creation Datetimecreated
property represents when the Request was created.
The created
property is similar to the started
property, in that when a Request starts, it is created. The created
property applies to when our API creates a Request, while the started
property pertains to when a user uses the user interface to start a Request.
Enter the datetime in the PMQL search query within quotation marks in the following format: YYYY-MM-DD HH:MM:SS
using 24-hour time. Example: "2020-07-01 14:25:15"
.
NOW
KeywordUse the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the interval unit of time is singular. PMQL supports the following units of time:
second
minute
hour
day
Purpose of the search: Find Requests for the Employee Onboarding Process that were created on or after July 1, 2020.
Note the following:
This example uses the AND
operator to search for multiple required property values.
This example uses the request
property. The request
property value ("Employee Onboarding Process"
) is not case-sensitive.
Purpose of the search: Find created Requests for the Student Enrollment Process that have been canceled or encountered an error.
Note the following:
This example uses multiple operators: AND
and OR
. The AND
operator searches for multiple required properties while the OR
operator within one of the AND
operators searches for any of multiple property values.
This example uses the status
property that uses the canceled
and error
values.
data
object: Search Request Data for Specific Request InformationUse the data
JSON object to search for Request data associated with the sought Request(s). The data
JSON object represents Request data: each Request's JSON data model contains the accumulation of all JSON objects and arrays for that Request. The data
JSON object also contains the record data for a Collection. The key names for each JSON object or array derive from the Variable Name setting values in the Screens used for Tasks in each Request or any data injected into that Request's JSON data model by Scripts run via Script Task elements or calls to the RESTful Application Program Interface (API).
Using the data
JSON object in PQML search queries helps answer the question "Which Request(s) have specific information in them that I seek?" Use operators to compare the value for a particular Screen control to find Requests that only contain the value(s) you seek. For example:
Search for Requests that apply to a specific customer in a Loan Request Process.
Search for Requests in a Purchase Request Process in which a purchase request amount is greater than $500 but less than $10,000.
Search for which registered conference attendees that were required to enter their job title are similar to "Product Manager," such as "Project Manager."
To determine what the Variable Name setting is for a control that stores Request information you seek, do one of the following:
View the Screen for the Task in which Request participants enter the information you seek, and then make note of the pertinent control's Variable Name setting. Note that your user account or group membership must have the Screens: View Screens permission.
View the Data tab in the summary for a completed Request to view the data from a completed Request, and then use the specific key name (represented in red-colored text) to search Request information from that control. Spaces are allowed between operators. Example: data.last_name = "Canera"
. Note that your user account or group membership must have the Requests: Edit Request Data permission. Ask your Administrator if you do not see the Data tab in completed Requests.
The data
JSON object precedes the Variable Name setting value, as noted above. Use JSON dot notation to reference sub-properties in the referenced Screen control if necessary.
Purpose of the search: Find Requests that the business customer named Acme Products submitted in a Loan Request Process.
When submitting a business loan request, the business must enter the business's name into a Line Input control of which its Variable Name setting is BusinessName
.
Note the following:
The examples for the data
object use the AND
operator to require all properties in the PMQL search query to be required.
These examples also use the request
property. The request
property value (such as"Loan Request Process"
) is not case-sensitive.
Purpose of the search: Find Requests associated with the Purchase Request Process in which the total purchase request cost amount is greater than $500 but less than $10,000.
A Line Input control of which its Variable Name setting is TotalCost
stores the total cost amount of the purchase request. This example uses two AND operators, one which determines the cost range.
id
: Request ID Numberid
property represents the Request ID number associated with the sought Request's Process as displayed in the # column of Request pages.
This id
property only applies to Request-related PMQL search queries, and is distinct from the id
property for the Task
data type or for the id
property for the Collection
data type.
Purpose of the search: Find Requests that are newer than Request ID 5.
Purpose of the search: Find Requests newer than Request ID 5 but older or the same as Request ID 10.
This example uses the AND
operator to require multiple property values for the search.
modified
: Datetime Request Was Last Modifiedmodified
property represents when the Request was last modified. A Request modifies when its JSON object model is changed from a Script, a user action, an application program interface (API) call, or any other means.
Enter the datetime in the PMQL search query within quotation marks in the following format: YYYY-MM-DD HH:MM:SS
using 24-hour time. Example: "2020-07-01 14:25:15"
.
NOW
KeywordUse the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the interval unit of time is singular. PMQL supports the following units of time:
second
minute
hour
day
Purpose of the search: Find Requests for the Student Enrollment Process that were modified on or after July 1, 2020 but before July 8, 2020.
Note the following:
This example uses the AND
operator to search for multiple required property values.
This example uses the request
property. The request
property value ("Student Enrollment Process"
) is not case-sensitive.
Purpose of the search: Find modified Requests for the Student Enrollment Process for Seniors in all Engineering-related majors except Mechanical Engineering in which their grade point average (GPA) is or less than 2.5.
Note that PMQL search queries are case sensitive. This example uses the data
object that represents Request data. The following Request variables store Request data that this PMQL search query references:
Grade: The Grade
Request variable stores which grade for each student is this year.
Major: The Major
Request variable stores the major for each student.
GPA: The GPA
Request variable stores the GPA for each student as a string. To do a numerical comparison, this example uses the CAST
function to convert the text to a number.
participant
: Request Participant by User Nameparticipant
property represents the user name(s) of the person(s) that have participated in the sought Request. Request participants display in the Participants column of Request pages.
Enter the participant
property value in quotation marks. Example: "lcanera"
. The property value is not case-sensitive.
Purpose of the search: Find Requests that started two days ago associated with the Account Opening Process in which lcanera
and jlowell
have participated.
Note the following:
This example uses the AND
operator to search for multiple required property values.
This example uses the request
property. The request
property value ("Account Opening Process"
) is not case-sensitive.
This example uses the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the chronological unit of measurement is singular (day
).
Purpose of the search: Find all Requests for Processes with IDs 10 and 12 except those in which bfrizzel
has participated.
Note that this example uses the process_id
property, which is the Process's ID number.
process_id
: Process ID Number Associated with the Requestprocess_ID
property represents the Process ID number associated with the sought Request(s).
Process IDs do not display in the Processes page. However, if you have Process permissions to edit Process models, then determine the Process ID by doing the following:
View your Processes. The Processes page displays.
From the Web browser address bar, note the number immediately after modeler/
. This number is the Process ID to use with the process_id
property.
Purpose of the search: Find Requests associated with Process IDs are 3 and 7. This example uses the OR
operator to search for any of multiple properties.
Purpose of the search: Find Requests that exclude those for Process ID 5. This example uses the Not Equal To operator (!=
) to exclude Process ID 5.
request
: Request Namerequest
property represents the name of the sought Request(s).
Request names display in the Name column of Request pages. The Name column displays the Process name associated with the Request.
Enter the request
property value in quotation marks. Example: "ProcessName"
. The property value is not case-sensitive.
Purpose of the search: Find all Requests associated with the Loan Approval Process.
Purpose of the search: Find in-progress Requests associated with the Loan Approval Process and are at least three days old.
Note the following:
This example uses the status
property. The status
property values (such as "in progress"
) are not case-sensitive.
This example uses the NOW
keyword to represent the current datetime, and then uses the Less Than operator (<
) to determine the datetime two days ago. Note that the unit of chronological measurement (day
) is singular.
requester
: Requester's User Namerequester
property represents the user name of the person who started the sought Request (called the Request starter).
Enter the requester
property value in quotation marks. Example: "lcanera"
. The property value is not case-sensitive.
Purpose of the search: Find all Requests started by either jlowell
or sparkles
. This example uses the OR
operator to search for any of multiple properties.
Purpose of the search: Find canceled Requests started by either jlowell
or sparkles
on or after July 1, 2020 associated with Processes that contain "Course" followed by any five characters in its name.
Note the following:
This example uses multiple operators: AND
and OR
. The AND
operator searches for multiple required properties while the OR
operator within one of the AND
operators searches for any of multiple property values.
This example uses the started
property to search for when Requests started by a particular date. Note that PMQL interprets strings in the format YYYY-MM-DD HH:MM:SS
as dates and can be used in comparative queries if that string is in quotation marks ("2020-01-01 00:00:00"
).
This example uses the request
property. The request
property value ("Course_____"
) is not case-sensitive.
This example uses the LIKE
operator: functioning as a wildcard, each underscore character (_
) represents one wildcard character up to the number of underscores in the string that is in quotation marks.
started
: Datetime Request Startedstarted
property represents when the Request starts.
The started
property is similar to the created
property, in that when a Request starts, it is created. The created
property applies to when our API creates a Request, while the started
property pertains to when a user uses the user interface to start a Request.
Enter the datetime in the PMQL search query within quotation marks in the following format: YYYY-MM-DD HH:MM:SS
using 24-hour time. Example: "2020-07-01 14:25:15"
.
NOW
KeywordUse the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the interval unit of time is singular. PMQL supports the following units of time:
second
minute
hour
day
Purpose of the search: Find Requests for the Travel Request Process that started on or after January 1, 2020, but before March 1, 2020.
Note the following:
This example uses the AND
operator to search for multiple required property values.
This example uses the request
property. The request
property value ("Travel Request Process"
) is not case-sensitive.
Purpose of the search: Find Requests for the Travel Request Process that started after March 1, 2020, in which their expected travel cost is at least $1,500, the departure date is later than March 7, 2020, and the return date is later than March 14, 2020. This example uses the data
object that represents Request data.
Note the following:
TotalCost: The TotalCost
Request variable stores the calculated total cost of the travel request.
Departure: The Departure
Request variable stores the requested departure date.
Return: The Return
Request variable stores the requested return date from travel.
status
: Request Statusstatus
property represents the status(es) for the sought Request(s).
Enter the status
property value in quotation marks. Example: "in progress"
. Values for the status property are not case-sensitive.
Use the following values for the status
property:
In Progress: The sought Request is in-progress.
Completed: The sought Request is completed. Using the "completed"
value is identical to using the completed
property.
Canceled: The sought Request has been canceled.
Error: The sought Request has an error.
Purpose of the search: Find completed Requests associated with the Student Enrollment Process in which the either lcanera
or bfrizzel
are Request participants.
Note the following:
This example uses multiple operators: AND
and OR
. The AND
operator searches for multiple required properties while the OR
operator within one of the AND
operators searches for any of multiple property values.
This example uses the request
property. The request
property value ("Student Enrollment Process"
) is not case-sensitive.
This example uses the participant
property. The participant
property value (such as "lcanera"
) is not case-sensitive.
Purpose of the search: Find completed Requests associated with the University Admission Process that completed at or prior to June 15, 2020.
Note that PMQL interprets strings in the format YYYY-MM-DD HH:MM:SS
as dates and can be used in comparative queries if that string is in quotation marks ("2020-06-15 00:00:00"
).
Use these ProcessMaker Query Language (PMQL) properties for Task PMQL search queries.
The following ProcessMaker Query Language (PMQL) properties apply to the Task
data type to perform PMQL search queries from any of the pages accessible from the Tasks top menu option. Selecting any PMQL search result displays the Task summary for that result.
completed
: Datetime Task Completedcompleted
property represents when the Task completes. The completed
property applies to Form Task, Manual Task, and/or Script Task elements from the Request that created the sought Task(s).
Enter the datetime in the PMQL search query within quotation marks in the following format: YYYY-MM-DD HH:MM:SS
using 24-hour time. Example: "2020-07-01 14:25:15"
.
NOW
KeywordUse the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the interval unit of time is singular. PMQL supports the following units of time:
second
minute
hour
day
Purpose of the search: Find completed Tasks named Student Registration in the Student Enrollment Process that completed after they were due three days ago.
Note the following:
This example uses the AND
operator to require multiple property values for the search.
This example uses the task
property. The task
property value ("Student Registration"
) is not case-sensitive.
This example uses the request
property. The request
property value ("Student Enrollment Process"
) is not case-sensitive.
This example uses the NOW
keyword to represent the current datetime, and then uses the Less Than operator (<
) to determine the datetime four (4) days ago for completed Tasks that completed later than when they were due three (3) days ago. Note that the unit of chronological measurements (day
) is singular.
Purpose of the search: Find completed Tasks named Submit Employment Application in the Candidate Review Process in which employment candidates had programming experience in at least JavaScript and Python and had "Manager" in a job title.
This example uses the LIKE
operator to find text in a specified JSON array within Request data. For example, PMQL finds the string JavaScript
in the key name CodingLanguages
regardless of what string precedes or follows the sought pattern because the %
wildcard before and after the sought pattern disregards all content in the JSON array preceding and following that pattern, respectively.
This example uses the data
object that represents Request data. The following Request variables store Request data that this PMQL search query references:
CodingLanguages: The CodingLanguages
Request variable stores one or more selections from a Select List control of programming languages in which the employment candidate has experience. The Request data stores the Select List control selection(s) in a JSON array that contains both the value and content for each option in the Select List control.
JobTitle: The JobTitle
Request variable stores the job title for each position the employment candidate held. A Loop control called Jobs
contains a set of controls to enter information about each position the candidate held, among them being a Select List control called JobTitle
.
created
: Task's Creation Datetimecreated
property represents when the Request creates the Task. The created
property applies to Form Task, Manual Task, and/or Script Task elements from the Request that created the sought Task(s).
Enter the datetime in the PMQL search query within quotation marks in the following format: YYYY-MM-DD HH:MM:SS
using 24-hour time. Example: "2020-07-01 14:25:15"
.
NOW
KeywordUse the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the interval unit of time is singular. PMQL supports the following units of time:
second
minute
hour
day
See Examples 1 and 2 how this property can apply to Service Level Agreement (SLA) contract compliance.
Purpose of the search: Find created Tasks from two hours ago named Package Purchased Items in the Fulfill Purchase Delivery Process that started less than 30 minutes ago.
Note the following:
This example uses the AND
operator to require multiple property values for the search.
This example uses the task
property. The task
property value ("Package Purchased Items"
) is not case-sensitive.
This example uses the request
property. The request
property value ("Fulfill Purchase Delivery Process"
) is not case-sensitive.
This example uses the started
property to find those Tasks that started 30 minutes ago.
This example uses the NOW
keyword to represent the current datetime, and then uses the Less Than operator (<
) to determine the datetime two (2) hours ago and 30 minutes ago that the applicable Task(s) was created and started, respectively. Note that the unit of chronological measurements (hour
and minute
) are singular.
Use a PMQL search query similar to this example to monitor how much time passes from when a Task was created and that Task starts. A PMQL query similar to this example can determine which Tasks are being started later than the sanctioned time period a Service Level Agreement (SLA) contract allows from when that Task was created. For example, if a SLA contract states that a Task applicable to the contract must start within 1.5 hours from when its Request creates it, use a PMQL search query similar to this example to find only those Tasks that started less than 30 minutes ago, therefore longer than the 1.5 hours allowed by the SLA contract.
Purpose of the search: Find created Tasks associated with the Node Identifier setting value node_6
in Requests associated with Process ID 12 from two hours ago that have completed less than 30 minutes ago.
Note the following:
This example uses the element_id
property to reference the Node Identifier setting value (node_6
) from the Process model for the sought Task's element.
This example uses the process_id
property to reference the Process ID number (12
) associated with the sought Task(s).
This example uses the completed
property. The completed
property value compares the datetime that the Task completed.
Use a PMQL search query similar to this example to monitor how much time passes from when a Task was created and that Task completes. A PMQL query similar to this example can determine which Tasks are being completed later than the sanctioned time period a Service Level Agreement (SLA) contract allows from when that Task was created. Unlike Example 1 that identifies the Task to monitor by its name, this example identifies the Task by its Node Identifier setting value in a specified Process model. Otherwise, this example serves a similar purpose to monitor SLA contract compliance as does Example 1.
data
object: Search Request Data for Specific Request InformationUse the data
JSON object to search for Request data associated with the sought Task(s). The data
JSON object represents Request data: each Request's JSON data model contains the accumulation of all JSON objects and arrays for that Request. The data
JSON object also contains the record data for a Collection. The key names for each JSON object or array derive from the Variable Name setting values in the Screens used for Tasks in each Request or any data injected into that Request's JSON data model by Scripts run via Script Task elements or calls to the RESTful Application Program Interface (API).
Using the data
JSON object in PQML search queries helps answer the question "Which Request(s) have specific information in them for Tasks that I seek?" Use operators to compare the value for a particular Screen control to find Requests that only contain the value(s) you seek. For example:
Search for Requests that apply to a specific customer in a Loan Request Process.
Search for Requests in a Purchase Request Process in which a purchase request amount is greater than $500 but less than $10,000.
Search for which registered conference attendees that were required to enter their job title are similar to "Product Manager," such as "Project Manager."
To determine what the Variable Name setting is for a control that stores Request information you seek, do one of the following:
View the Screen for the Task in which Request participants enter the information you seek, and then make note of the pertinent control's Variable Name setting. Note that your user account or group membership must have the Screens: View Screens permission.
View the Data tab in the summary for a completed Request to view the data from a completed Request, and then use the specific key name (represented in red-colored text) to search Request information from that control. Spaces are allowed between operators. Example: data.last_name = "Canera"
. Note that your user account or group membership must have the Requests: Edit Request Data permission. Ask your Administrator if you do not see the Data tab in completed Requests.
The data
JSON object precedes the Variable Name setting value, as noted above. Use JSON dot notation to reference sub-properties in the referenced Screen control if necessary.
Purpose of the search: Find in-progress Tasks named Approve Semester Courses in the Student Enrollment Process in which Business majors have enrolled in at least 18 credits this semester.
When submitting which courses to enroll that semester, each student must enter the following information into a Screen that becomes Request data when that Screen is submitted:
A Select List control of which its Variable Name setting is Major
stores the JSON object value for the option that each student selects as a major.
A Line Input control of which its Variable Name setting is TotalCredits
stores as an integer the sum of all credits that the student selected for enrollment.
Note the following:
This example uses the AND
operator to require multiple property values for the search.
This example uses the status
property. The status
property values (such as "in progress"
) are not case-sensitive.
This example uses the task
property. The task
property value ("Approve Semester Courses"
) is not case-sensitive.
This example uses the request
property. The request
property value ("Student Enrollment Process"
) is not case-sensitive.
Purpose of the search: Find completed Tasks named Submit Leave Request in the Leave Request Process in which the reason those employees requested leave was illness between the dates March 15, 2020, and April 30, 2020.
When submitting a leave request, each employee must select from one of several options in a Checkbox control to indicate the reason for the leave request. The Checkbox control has a Variable Name setting of LeaveType
; the option that indicates the reason is for medical leave has an option value of Medical
. Therefore, to find those completed Tasks in which the reason for leave is illness, use the following in the PMQL search query: data.LeaveType = "Medical"
. The PMQL search query is case sensitive.
Note the following:
This example uses the completed
property. Each use of the completed
property compares the datetime that the Task completed.
PMQL interprets strings in the format YYYY-MM-DD HH:MM:SS
as dates and can be used in comparative queries if that string is in quotation marks ("2020-03-15 00:00:00"
).
due
: Datetime Task Is or Was Duedue
property represents when the Task is or was due. The due
property applies to Form Task, Manual Task, and/or Script Task elements from the Request that created the sought Task(s).
Enter the datetime in the PMQL search query within quotation marks in the following format: YYYY-MM-DD HH:MM:SS
using 24-hour time. Example: "2020-07-01 14:25:15"
.
NOW
KeywordUse the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the interval unit of time is singular. PMQL supports the following units of time:
second
minute
hour
See Example 2 how this property can apply to Service Level Agreement (SLA) contract compliance.
Purpose of the search: Find Tasks named Loan Review that are due in two days for the Loan Approval Process.
Note the following:
This example uses the AND
operator to require multiple property values for the search.
This example uses the task
property. The task
property value ("Loan Review"
) is not case-sensitive.
This example uses the request
property. The request
property value ("Loan Approval Process"
) is not case-sensitive.
This example uses the NOW
keyword to represent the current datetime, and then uses the Greater Than operator (>
) to determine the datetime two (2) days from now for due Tasks. Note that the unit of chronological measurements (day
) is singular.
Purpose of the search: Find Tasks that completed 20 minutes ago that were past due for Requests associated with process ID 25.
Note the following:
This example uses the completed
property. The completed
property compares the datetime that the Task completed. Since the PMQL search query finds completed Tasks past due, the due
property uses the Greater Than operator (>
) to find Tasks that were due later than 20 minutes ago.
This example uses the process_id
property with a value of 25
to find Requests associated with that Process.
element_id
: Task Node Identifier from the Process Modelelement_id
property is the Node Identifier setting value from the Process model for the sought Task's element. The element_id
property applies to Form Task, Manual Task, and/or Script Task elements from the Process model that started the sought Task(s).
Enter the node identifier value in the PMQL search query within quotation marks. The node identifier value is not case-sensitive. Example: "node_15"
.
if you have Process permissions to edit Process models, then determine the Node Identifier setting value for a Form Task, Manual Task or Script Task element by doing the following:
Select the Form Task, Manual Task, or Script Task element from the Process model from which to include in the PMQL search query. Panels to configure this element display.
Expand the Advanced panel if it is not presently expanded. The Node Identifier setting value displays.
See Example 2 how this property can apply to Service Level Agreement (SLA) contract compliance.
Purpose of the search: Find in-progress Tasks associated with the Node Identifier setting value node_4
in Requests associated with Process ID 10.
Note the following:
This example uses the AND
operator to require multiple property values for the search.
This example uses the status
property. The status
property values (such as "in progress"
) are not case-sensitive.
This example uses the process_id
property with a value of 10
to find Requests associated with that Process.
Purpose of the search: Find in-progress Tasks associated with the Node Identifier setting value node_4
in Requests associated with Process ID 10 that started two days ago.
Note the following:
This example uses the started
property in conjunction with the NOW
keyword, described below.
This example uses the NOW
keyword to represent the current datetime, and then uses the Less Than operator (<
) to determine the datetime two (2) days ago that the applicable Task(s) started. Note that the unit of chronological measurement (day
) is singular.
Use a PMQL search query similar to this example to monitor which started Tasks are at risk of completing past the sanctioned time period a Service Level Agreement (SLA) contract allows. For example, if a SLA contract states that a Task applicable to the contract must complete within three (3) days from when it starts, use a PMQL search query similar to this example to find only those Tasks that started two days ago to determine which are at risk of not complying with the SLA contract.
id
: Task ID Numberid
property represents the Task ID number for the sought Task(s). The id
property applies to Form Task, Manual Task, and/or Script Task elements from the Request that started the sought Task(s).
This id property only applies to Task-related PMQL search queries, and is distinct from the id
property for the Request
data type or for the id
property for the Collection
data type.
Purpose of the search: Find Tasks that are newer than Task ID 5.
Purpose of the search: Find Tasks newer than Task ID 5 but older or the same as Task ID 10.
This example uses the AND
operator to require multiple property values for the search.
modified
: Datetime Task Last Modifiedmodified
property represents when the Task was last modified. A Task modifies when the JSON object model to which that Task applies is changed from a Script, a user action, an application program interface (API) call, or any other means. The modified
property applies to Form Task, Manual Task, and/or Script Task elements from the Request that created the sought Task(s).
Enter the datetime in the PMQL search query within quotation marks in the following format: YYYY-MM-DD HH:MM:SS
using 24-hour time. Example: "2020-07-01 14:25:15"
.
NOW
KeywordUse the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the interval unit of time is singular. PMQL supports the following units of time:
second
minute
hour
day
Purpose of the search: Find Tasks modified 20 minutes ago named Loan Information in the Loan Application Process.
Note the following:
This example uses the AND
operator to require multiple property values for the search.
This example uses the task
property. The task
property value ("Loan Information"
) is not case-sensitive.
This example uses the request
property. The request
property value ("Loan Application Process"
) is not case-sensitive.
This example uses the NOW
keyword to represent the current datetime, and then uses the Less Than operator (<
) to determine the datetime 20 minutes ago that the applicable Task(s) were modified. Note that the unit of chronological measurement (minute
) is singular.
Purpose of the search: Find any Task modified between 30 minutes ago and one hour which have "approval" in its name from Requests associated with Process ID 25.
Note the following:
This example uses the process_id
property to reference the Process ID number (25
) associated with the sought Task(s).
This example uses the LIKE
operator with the %
wildcard to search for any Task name that includes the characters approval
in its name.
process_id
: Process ID Number Associated with the Taskprocess_ID
property represents the Process ID number associated with the sought Task(s). The process_ID
property applies to Form Task, Manual Task, and/or Script Task elements from the Process model associated with the Process ID that started the sought Task(s).
Process IDs do not display in the Processes page. However, if you have Process permissions to edit Process models, then determine the Process ID by doing the following:
View your Processes. The Processes page displays.
From the Web browser address bar, note the number immediately after modeler/
. This number is the Process ID to use with the process_id
property.
Purpose of the search: Find Tasks associated with Process IDs are 3 and 7.
This example uses the OR
operator to search for any of multiple properties.
Purpose of the search: Find Tasks that exclude those for Process ID 5. This example uses the Not Equal To operator (!=
) to find all Tasks except those associated with Process ID 5.
request
: Request Name Associated with the Taskrequest
represents the Request's name associated with the sought Task(s). The request
property applies to Form Task, Manual Task, and/or Script Task elements from the Process model that started the sought Task(s).
Request names display in the Name column of Request pages. The Name column displays the Process name associated with the Request.
Enter the request
property value in quotation marks. Example: "Request Name"
. The property value is not case-sensitive.
See Example 2 how this property can apply to Service Level Agreement (SLA) contract compliance.
Purpose of the search: Find completed Tasks started from either the Residential Loan Approval Process or the Business Loan Approval Process.
Note the following:
This example uses the AND
operator to search for multiple required property values.
This example uses the OR
operator to search for any of multiple properties within an AND
operator to find Tasks for either the "Residential Loan Approval Process" or "Business Loan Approval Process" Requests.
This example uses the status
property. The status
property values (such as "completed"
) are not case-sensitive.
Purpose of the search: Find in-progress Tasks started one hour ago for the Purchase Order Fulfillment Process for which the purchase order amount is at least $10,000 for Acme Corporation.
Note that this example uses the NOW
keyword to represent the current datetime, and then uses the Less Than operator (<
) to determine the datetime one hour ago that the applicable Task(s) started. Note that the unit of chronological measurement (hour
) is singular, even if the sought Task(s) is more than one hour old.
This example uses the data
object that represents Request data. The following Request variables store Request data that this PMQL search query references:
TotalPurchase: The TotalPurchase
Request variable stores the total purchase request amount, including applicable taxes.
Customer: The Customer
Request variable stores the business name for which the purchase order fulfillment applies.
Use a PMQL search query similar to this example to track which started Tasks are at risk of completing past the sanctioned time period a Service Level Agreement (SLA) contract allows. For example, if a SLA contract states that a Task applicable to the contract must complete within two (2) hours from when it starts for specific customers and/or for specific purchase order amounts, use a PMQL search query similar to this example to find only those Tasks that an hour ago to determine which are at risk of not complying with the SLA contract.
started
: Datetime Task Startedstarted
property represents when the Task starts. The started
property applies to Form Task, Manual Task, and/or Script Task elements from the Request that started the sought Task(s).
The started
property is similar to the created
property, in that when a Task starts, it is created. The created
property applies to when our API creates a Task, while the started
property pertains to when a user uses the user interface to start a Task.
Enter the datetime in the PMQL search query within quotation marks in the following format: YYYY-MM-DD HH:MM:SS
using 24-hour time. Example: "2020-07-01 14:25:15"
.
NOW
KeywordUse the NOW
keyword to dynamically compare the current datetime with a specified number of chronological units. Use the Less Than operator (<
) followed by the number of chronological units to search for Requests of that age. Note that the interval unit of time is singular. PMQL supports the following units of time:
second
minute
hour
day
Purpose of the search: Find in-progress Tasks named Submit Purchase Request that started on July 1, 2020, for the Purchase Request Process.
Note the following:
This example uses the AND
operator to search for multiple required property values.
This example uses the task
property. The task
property value ("Submit Purchase Request"
) is not case-sensitive.
This example uses the status
property. The status
property values (such as "in progress"
) are not case-sensitive.
This example uses the request
property. The request
property value ("Purchase Request Process"
) is not case-sensitive.
Purpose of the search: Find completed Tasks named Purchase Authorization that started three days ago associated with the Purchase Request Process for which the approved total purchase amount was more than $100,000.
Note that this example uses the NOW
keyword to represent the current datetime, and then uses the Less Than operator (<
) to determine the datetime three (3) days ago that the applicable Task(s) started. Note that the unit of chronological measurement (day
) is singular.
This example uses the data
object that represents Request data. The following Request variables store Request data that this PMQL search query references:
Approve: The Approve
Request variable stores whether a Checkbox control is selected in the Form Task that approves a submitted purchase request. Since this example requires only approved purchases, this PMQL search query includes only Approve
values of true
that a Checkbox control stores when it is selected upon Task submission. The property value is not case-sensitive.
TotalPurchase: The TotalPurchase
Request variable stores the total purchase request amount, including applicable taxes.
status
: Task Statusstatus
property represents the Task status. The status
property applies to Form Task, Manual Task, and/or Script Task elements from the Request that started the sought Task(s).
Task status displays in the Status column of Task pages.
Enter the status
property value in quotation marks. Example: "in progress"
. The property value is not case-sensitive.
Purpose of the search: Find in-progress Tasks for the Travel Request Process.
Note the following:
This example uses the AND
operator to search for multiple required property values.
This example uses the request
property. The request
property value ("Travel Request Process"
) is not case-sensitive.
Purpose of the search: Find in-progress Tasks for the Travel Request Process for which the business travel destination is to any municipality named Dallas except that in Texas to leave three (3) days from today.
Note that this example uses the NOW
keyword to represent the current datetime, and then uses the Greater Than operator (>
) to determine the datetime three days from now that the requested business travel is to occur as requested in the LeaveDate
Request variable. Note that the unit of chronological measurement (day
) is singular.
This example uses the data
object that represents Request data. The following Request variables store Request data that this PMQL search query references:
DestinationMunicipality: The DestinationMunicipality
Request variable stores to which municipality business travel is requested.
DestinationState: The DestinationState
Request variable stores to which state business travel is requested.
LeaveDate: The LeaveDate
Request variable stores at which datetime business travel is requested.
task
: Task Nametask
property represents the Task name. The task
property applies to Form Task, Manual Task, and/or Script Task elements from the Request that started the sought Task(s).
Task names display in the Task column of Task pages.
Enter the task
property value in quotation marks. Example: "TaskName"
. The property value is not case-sensitive.
Purpose of the search: Find completed Tasks named Review Risk Rating.
Note the following:
This example uses the AND
operator to search for multiple required property values.
This example uses the status
property. The status
property values (such as "in progress"
) are not case-sensitive.
Purpose of the search: Find in-progress Tasks that contain the word "review" in its name for Requests associated with process ID 12.
Note the following:
This example uses the LIKE
operator with the %
wildcard to search for any Task name that includes the characters review
in its name.
This example uses the process_id
property with a value of 12
to find Requests associated with that Process.
Click the Open Modeler iconto edit the Process model associated with the sought Requests. Process Modeler displays.
Ensure that the Hide Menus buttonis not enabled. See Maximize the Process Modeler Canvas View.
Click the Open Modeler iconto edit the Process model associated with the sought Requests. Process Modeler displays.