Post

2 followers Follow
0
Avatar

REST API: Using /data/createAndRetrieve and data/CountQuery

It looks like there are some gaps in the Clarizen REST API documentation that I have been using (https://api.clarizen.com/V1.0/services/) and am having some issues in determining what parameters need to be passed to the data/createAndRetrieve and the data/countQuery endpoints. For the data/createAndRetrieve endpoint, it looks like it takes a property of type array named "fields" with all of the fields that I want returned after the entity has been created; is this assumption correct? Also, there is another property that it takes called "entity", which takes a json object with all of the field names and values that I want to create for this new entity, as well an entity id string. My confusion lies in what the value of this id string should be. If I am creating a new entity, shouldn't the id of this new entity be automatically created for me? It would be very helpful to have an example createAndRetrieve POST request body so that I can see what the correct way of going about this is.

Another question I had was around the data/countQuery endpoint. Does this call run the query you provide in the POST request and just tells you the total of how many potential results will be brought back from the query? How many transactions are charged for this kind of call? I can see that it takes a single property called "query" but it is unclear what the query json object would look like. The documentation simply has a paging item under the list of properties. If I could get a sample call for this as well it would make things much easier.

Thank you!

Alex Ayala Answered

Please sign in to leave a comment.

3 comments

0
Avatar

Here's an example of creating a task and retrieving back some of it's fields:

POST /data/createAndRetrieve

{ entity: {id: "/task", name: "taskName"}, fields: ["Name", "CreatedBy"] }

 

As you can see above, the id field contains only the type name.

The query parameter of countQuery should be another Query. Usually you will pass here an entityQuery.

The format of the entityQuery is the same one you are using in the /data/entityQuery call but since you need to somehow "hint" the system that this is an entityQuery, you should add a _type field to the query.

So if, for example, you are querying all tasks in the system where you are the manager:

POST /data/entityQuery

{ typeName: "task", where: {leftExpression: {fieldName: 'Manager'}, operator: 'Equal', rightExpression: {value: '/User/XX-YY0ZZ'}} }

 

you would count that by doing this:

POST /data/countQuery

{query: {_type: "entityQuery", typeName: "task", where: {leftExpression: {fieldName: 'Manager'}, operator: 'Equal', rightExpression: {value: '/User/XX-YY0ZZ'}}}}

 

hope this helps, and let me know if you have additional questions!

 

Eyal Post 0 votes
Comment actions Permalink
0
Avatar

This is very helpful. Thank you so much for this! Will the countQuery endpoint just return the count of the first 100 results, or all of them?

Alex Ayala 0 votes
Comment actions Permalink
0
Avatar

The countQuery counts all (which means it can be very slow at times).

Eyal Post 0 votes
Comment actions Permalink