A custom object can be transitioned from one workflow state to another through the API. A custom object instance's actionSet, which is the actions that your user has the security rights to take on an object, can be obtained by hitting the objects actionSet endpoint. That API request will be resemble the following structure, with more verbose instructions here
To find a complete list of an objects possible states and actions, refer to the Platform Modules object design page. The action that needs to be performed is listed in the Action column. Take the DiscussionThread object for example, the workflow information is recorded in the status field. In order for an open discussion thread (status = open) to reach the closed state, the closeDiscussion action must be performed on the thread.
The workflow transition request is very similar to an update request. You still need the If-Match header that holds the object's fingerprint, so the transition will only be processed if the fingerprint matches the one on the server. There is a new parameter {workflowAction}, which is the action that must be performed for the transition.
| Method | POST |
| Base URL | https://demo.infornexus.com/rest/{versionNumber}/{objectType}/{uid}/actionSet/wf_{workflowAction} |
| Header | x-nexus-api-key={datakey} |
| Authorization: {authorizationToken} | |
| Content-Type: application/json | |
| If-Match: {fingerprint} | |
| Body | {objectData}*optional |
The values of the variables are as follows.
| {versionNumber} | Version number of the API, i.e., 3.1. |
| {objectType} | The URL-encoded global type of an object. |
| {uid} | The unique ID of the object instance. |
| {workflowAction} | The action of the workflow transition step being preceded with wf_, e.g. closeDiscussion or reopenDiscussion. |
| {datakey} | The data key you obtained in the data key tutorial. |
| {authorizationToken} | The authorization token you obtained in the authentication tutorial, starting with the word Token. |
| {fingerprint} | The ETag or fingerprint of the object's instance, enclosed in double quotes, e.g. "0dc497ab506a35843a0706f35105aec6". |
| {objectData}*optional |
You can optionally pass in your objects data representation.
If you pass in your instance's JSON representation as the body of your request,
a save will persist before the object is transitioned. However, you must ensure your user has modify
rights on the object; if you attempt to pass a modified object representation when you don't have modify rights, the save will fail and the transition will not be executed.
|
When the workflow transition request is successful, it will return a 202 Accepted status code, and a response body as follows.
| Body | A JSON object that contains an acknowledgement of the workflow transition. Because a workflow transition is asynchronous, the JSON object only signals the action has been initiated but does not contain the transitioned custom object itself. The transition.futureId field provides a value you can use to poll the result of the asynchronous request when it is completed, but it is not necessary to do so for this tutorial. The response body should look something like this:
|
If the transition is not valid (e.g. the requested action is not allowed on the current state, or you are not in the permitted action roles), it will return a 403 Forbidden status.
Another thing worthy of note is, all the workflow rules you established in the Platform Console are enforced at the API level as well. Take a discussion thread object for example, if the org that your user account belongs to is not the ObjectCreator (the org that created the particular discussion thread instance), you will be forbidden to transition the workflow of that instance. Open the screenshot above, and you can see this rule specified in the Action Roles column. If you attempt to perform the closeDiscussion action on a thread that is already at the closed status, you will receive a forbidden status as well.
Since a discussion thread is read-only when it is at the closed status, if you attempt to update the object values at that time, you will receive a forbidden status. In addition, you are forbidden to update the status field to any value other than open and closed at any point in the life cycle of a discussion thread, because it is not a valid value.
To generate the cURL syntax for your specific API call, enter the appropriate values in the following widget and click the "Generate cURL Syntax" button.
| Version Number | |
| Object Type | |
| Uid | |
| Workflow Action | |
| Datakey | |
| Authorization Token | |
| Fingerprint | |
| Object Data | |
cURL Call:
So far we have learned how to work with an individual object. Next, we will take a look at how to run an existing report from the API to retrieve a group of objects.