Graphql
Userapp
This document is an introduction to the queries and mutations you can use to retrieve data from the userapp
Permissions
The term permission
is a term for any role, userappResource or workflow a user can request. You can get a list of available permissions for the logged in user by using the viewer
query. This query can be filtered with a where
parameter as well as sorted and paginated with the sort
and paging
parameters. To find out how to filter the permissions, the best way would be to try the query out in the playground. The following example shows a simple filtering.
query SearchViewerPermissions {
viewer {
permissions(
where: { type: role },
paging: { limit:5 },
sort: { by: name, order: ASCENDING }
) {
nodes {
id
label
description
}
}
}
}
This query will return a connection with the first 5 (for the logged in user available) permissions that are of the type role
sorted by name ascending.
With the id
of a permission you can also request only this particular permission likfe follows:
query FindViewerPermission {
viewer {
permission(id: "xxx") {
id
label
description
}
}
}
Please check the docs in the playground for further information on the UserappPermission
type that is returned by these queries.
To request a permission you can utilize the requestPermission
mutation. You have to pass the input
parameter, at least containing the id
of the permission to request and a reason
, which is a string that describes why you want to request the permission. You have the possibility to pass additional parameters like an expirationDate
. See the playground docs for more information.
The mutation returns the fields shown below in the example query. The success
field tells you if the request was successful. If not, you may check the error
field to see what was going wrong. If successful, you can get informatoion on the permission
you just requested (with all fields of the type UserappPermission
). The recipient
field gives you all information of the user the permission was requested for. If you don't pass the id
of a user as recipient
in the input
parameter, the logged in user is used as recipient. The last field is request
with that you can query the created UserappRequest
.
mutation RequestPermission {
requestPermission(
input: {
id: "xxx",
reason: "this is why"
}) {
success
permission {
label
}
recipient {
firstName
lastName
}
request {
label
}
error {
message
}
}
}
You can request a permission for multiple recipients. The mutation requestPermissions
, that you have to use for that, works exactly the same as requestPermission
, but you can pass an array of ids of recipients:
mutation RequestPermissions {
requestPermissions(
input: {
id: "xxx",
reason: "this is why",
recipients: ["USERID1", "USERID2", "USERID3"]
}) {
success
operations {
permission {
label
}
recipient {
firstName
lastName
}
request {
label
}
error {
message
}
}
}
}
The returned result provides a success
field that tells you if every single request was successful and an array operations
, that contain the same fields as described for requestPermission
but for the request for every recipient you passed in the input
parameter.
Tasks
After a UserappPermission
was requested, a UserappTask
is created by the userapp. Every task is assigned to somebody that has to handle it. You can receive your tasks with the viewer
query. You will receive a connection of tasks, which means you can use sorting and paging. Also the where
parameter provides some properties to narrow down the results. Please check the playground docs for more details.
query SearchViewerTasks {
viewer {
tasks(
where: { q: "test" },
paging: { limit: 5 },
sort: { by: createTime }
) {
nodes {
id
label
}
}
}
}
Again you may request a single UserappTask
by using the corresponding query and providing an id:
query FindViewerTask {
viewer {
task(id: "xxx") {
id
label
}
}
}
To edit a task that is assigned to you, use the taskAction
mutation. It takes an input
parameter that has to contain at least of the fields id
(the id of the task to edit) and an action
field that chooses if you want to approve
, deny
or refuse
the request. Additionally you may provide a comment
and a data
object that can be used by the userapp for further processing.
mutation TaskAction {
taskAction(
input: {
id: "xxx"
action: approve
comment: "that's ok"
data: { a: "data", b: 2 }
}
) {
success
message
}
}
The response tells you by the success
field if the operation was successful and a message
provided by the userapp.
Others
There are more userapp queries you can access via the viewer
or user
query. As these are self-explanatory they are only listed and will not be described in detail.
Assignments
Query all or a single UserappAssignment
query SearchViewerAssignments {
viewer {
assignments(
where: { q: "test" }
paging: { limit: 5 }
sort: { by: name }
) {
nodes {
id
name
}
}
assignment(id: "xxx") {
id
name
}
}
}
Requests
Query all or a single UserappRequests
query SearchViewerRequests {
viewer {
requests(
where: { q: "test" }
paging: { limit: 5 }
sort: { by: createTime }
) {
nodes {
id
name
}
}
request(id: "xxx") {
id
name
}
}
}