Special Characters in API Call PMQL Searches

Use special characters, such as &, within PMQL searches when getting Request, Task, or Collection data.

Special Characters in API Call PMQL Searches

Perform ProcessMaker Query Language (PMQL) searches in ProcessMaker Platform's Application Program Interface (API) calls using any properties of the following data types:

Learning this powerful tip how to perform PMQL searches via API calls allows you to perform PMQL searches without using the ProcessMaker user interface. However, having experience making API calls, which is an advanced skill most often performed by software developers and administrators, makes understanding this tip easier.

Understanding how to perform API calls is outside the scope of this topic.

Use special characters, such as &, within PMQL searches when getting Request, Task, or Collection data while calling a ProcessMaker Platform API endpoint. To do so, special characters used in API calls must be Uniform Resource Identifier (URI) compliant.

For example, the following API call that gets Collection records from Collection ID 2 that contain tables & chairs in their names does not work because after the property collection data.name there are specials characters such as the =, ", space, and  & .

pm_server_name represents the name of your ProcessMaker Platform instance.


https://pm_server_name/api/1.0/collections/collection/2/records?pmql=data.Name="tables & chairs"

Follow these steps to make that includes a special character in a ProcessMaker Platform API call:

  1. Ensure that your Administrator has created client authentication for your user account. If not, contact your Administrator.

  2. Visit a Website that converts special characters to be URI-compliant, such as OnlineWebToolKit.

  3. Copy the special character(s) in your ProcessMaker Platform API endpoint call into the URI converter Website, and then click to encode the special character(s) to be URI-compliant.

    Referencing the example above, copy all the content after data.name from the API endpoint URL to encode it. The encoding tool converts the characters ="tables & chairs" to %3D%22tables%20%26%20chairs%22.

  4. Paste the URI-encoded special character(s), and then replace the non-encoded special character(s) in your API endpoint URL.

    Referencing the example above, replace the ="tables & chairs" in the ProcessMaker Platform API endpoint URL with %3D%22tables%20%26%20chairs%22 as follows: https://pm_server_name/api/1.0/collections/collection/2/records?pmql=data.Name%3D%22tables%20%26%20chairs%22

  5. Call the ProcessMaker Platform API endpoint that now includes the URI-encoded special character(s).