Best Practices When Using Resource Query Language (RQL)

When using Resource Query Language (RQL) there are a number of issues you should bear in mind to ensure that your processes operate most efficiently when deployed. Planning when designing your process and RQL can save problems later on.

• All RQL is dynamic, so there are design implications because of that. You should be aware that changes to the deployed organization model will be reflected in the RQL results set after a period of time.
• Model your system as relevant to the application - this will almost certainly not be the same as the durable organization you may see in an organization chart. If you do you will not need to use RQL in most cases.
• RQL is more complex than using basic participants. Where possible use basic participants - and only use RQL for special cases.
• In both new and existing projects, consider whether you need to use RQL at all, or whether it can be replaced more efficiently with Dynamic Organization Participants. Dynamic Organization Participants allow you to do many actions without the overhead of RQL and are quicker. Dynamic Participants only allow valid actions, and at runtime they perform better than RQL because you are explicitly specifying an internal identifier for an organization entity (GUID). So there is instant lookup, with no parsing. Using Dynamic Organization Participants is the preferred way of dynamically assigning work. See Dynamic Organization Participants.
• Work items allocated using RQL do not appear in any managed work lists as they are not directly associated with specific organizational entities. You should use dynamic performer fields to get the association of work items to organizational entities functionality. See Using a Performer Data Field or Parameter to Dynamically Define a Participant.
• Use RQL when you want to reference LDAP attributes or reference capabilities.
• When you deploy an organization model it is cached in memory. Actions using this in memory cache are quick ( for example, RQL using references to an orgunit in the model). However, RQL that references resources will make calls to the database takes time.
• If you are looking at all LDAP attributes on a resource, looking them up in LDAP is time-consuming. If combined with operators such as OR, then it will be even slower.
• You need to use RQL for more complicated queries - those involving union, intersect, and qualifying LDAP attributes for example.
• You could produce valid RQL which does not identify any actual resources. You will not receive any warning that this will happen, so need to be careful to understand the results of the RQL you are providing.
• RQL cannot refer to Dynamic Organization Units (as these are replaced with dynamic instances at runtime).

Examples of Usage of RQL

When deciding what RQL queries to make, you should plan to minimize the number of calls they make to the database to make them efficient. For information on what options are available, see Organization Entities.

orgunit(name='KEYTeam').position(name='AdditionalStaff') union orgunit(name='Agency').position(name='Contractor')

This example queries the organization unit called KEYTeam and for positions called "AdditionalStaff". It then joins the result of this to a query of the organization unit called Agency, and the results who have the position Contractor.

orgunit(name='KEYTeam').position(name='Director' or name='Management').capability (name='Language' qualifier='French' )

This example queries the organization unit called KEYTeam, and for positions named either Director or Management where the resource in the position has a capability of French language.

orgunit(name='KEYTeam').position(name='AdditionalStaff') intersect resource(attribute.Area='DACH')

This example will find all the resources which have an LDAP attribute of AREA that is equal to DACH. This will take some time because of the querying of LDAP for all resources defined in BPM.

(orgunit(name='KEYTeam').all() intersect not orgunit(name='Management').position(name='*')) union orgunit(name='Vice Presidents*').position(name='Permanent')

This is an example of a complex RQL statement that takes excessive time, as it makes multiple calls on the database to resolve resource queries.