Initiate Workflow from REST

Ed Davis · June 17, 2020

Very frustrating getting information and examples for the REST API. Looking for either some extended documentation on initiating a workflow from the REST API. I see references in the API (Processes : Manage processes / workflows) and some dated discussions regarding (Draftprocesses: Manage draft processes) with Alpaca. Simply (or not) want to initiate a workflow preferably with form attributes, workflow attributes (parameters???) so I can at least reference an ObjectID in the workflow for processing. Any help would be appreciated.

Greg Griffiths · June 26, 2020

have you tried the advice from https://forums.opentext.com/forums/support/discussion/295587/workflow-rest-api-question-content-server-16-2 ?

Looks like you should be able to call api/v2/process/<mapid>/definition to load the map into your REST code, from where you should be able to edit the details before calling api/v2/processes to intiate the Workflow.

Ed Davis · June 26, 2020

Appreciate the response Greg, but here in-lies the problem. I am have looked inside out, upside down in the KB's, Documentation and Forums on guidance and examples on this, but nothing. Like you said, you look at the API documentation and you can tell how to make the call, but no template or example for the request and return packages. I know you are a power user and respected consultant within the OTCS community so I get very nervous (and validated) when I here you say "Looks like you should be able to". OT does a such a bad job at providing documentation and examples considering the cost of the product. I'm sure someone at OT knows exactly what the answer. I even got so frustrated that I pulled a support ticket for a similar question. The response I was provided is that "we don't answer this types of questions in Support, go to the forums or engage Professional Services" (for a fee). I really don't want to be negative and it's really too bad as we are doing great things with the platform but get stymied by lack of available information.

Thanks so much, like I said, I appreciate your help ...

Ed

Mario Cano · July 3, 2020

hello have a problem maybe can help me

Error preparing the workflow map can initiate the workflow

Hello my workflow is of 508 positions and send me the error Error preparing the workflow map can initiate the workflow, is very big analyse that

the data base is HANA, and is diferent that SQL and verify that the error is the next:

07/01/2020 11:30:34 ERROR [343103012465] 0000271793: ODBC diagnostic error: 1 ODBC error code: 274 ODBC state: S1000 ODBC error: [SAP AG][LIBODBCHDB DLL][HDBODBC] General error;274 inserted value too large for column: Failed in "MAPTASK_TRUELINKS" column with the value '4000000000000000000000000000000000000000000000000000000000000000000000000000000000'
07/01/2020 11:30:34 ERROR [343103012553] 0000271794: KSqlCursor::Execute() --> 'Could not execute cursor.'
07/01/2020 11:30:34 INFO [343103013069] 0000271795: KSqlCursor::Close() --> 'SUCCESS'
07/01/2020 11:30:34 ERROR [343103013134] 0000271796: KSql::Execute(...) --> 'Error executing an Sql statement.',0 records,[sec: 0 msec: 3]
07/01/2020 11:30:34 ERROR [343103013167] 0000271797: KSql::ExecuteN(...) --> 'Error executing an Sql statement.',0,[sec: 0 msec: 3]
07/01/2020 11:30:34 ERROR [343103014804] 0000271798: WMap::SaveMap(31831630) --> 'Could not create all tasks.'
07/01/2020 11:30:34 ERROR [343103014870] 0000271799: WWork::PrepareMap() --> 31831630,'Could not create all tasks.'
07/01/2020 11:30:34 ERROR [343103014903] 0000271800: KSql::EndTransaction('Could not create all tasks.',FALSE) --> 1
07/01/2020 11:30:34 INFO [343103014926] 0000271801: KConnect::EndTransaction --> DiffStart[sec: 0 msec: 60], DiffLast[sec: 0 msec: 60]
07/01/2020 11:30:34 ERROR [343103017425] 0000271802: KSql::EndTransaction('Scripting requested rollback.',FALSE) --> 0

I think that need changed/been customized with any of the livelink tables. and increase the size of the below columns to 4000.

Make a back up of the database in HANA for not run risks
Tis is the tablesand the fields

Table: WMAPTASK
FIELDS: MAPTASK_FORM
FIELDS:MAPTASK_DESCRIPTION
FIELDS: MAPTASK_PAINTER
FIELDS: MAPTASK_CONDITION

Table: WMAP
FIELDS:MAP_PAINTER
FIELDS:MAP_USERDATA

Run in this form in thedatabase

ALTER table WMAP MODIFY ( MAP_PAINTER %type_char_4000% )

ALTER table WMAP MODIFY ( MAP_USERDATA %type_char_4000% )

ALTER table WMAPTASK MODIFY (MAPTASK_FORM %type_char_4000% )

ALTER table WMAPTASK MODIFY (MAPTASK_DESCRIPTION %type_char_4000% )

ALTER table WMAPTASK MODIFY (MAPTASK_PAINTER %type_char_4000% )

ALTER table WMAPTASK MODIFY (MAPTASK_CONDITION %type_char_4000% )

But send me error of syntax, Do you have an idea of how to run the commands or I have to use subworkflows to lower the number of steps and if they have a manual or an example of a subworkflow MAP to follow it

Thanks Mario

Greg Griffiths · July 5, 2020

Ed,

Did a little digging using both the client and OScript code side, with a huge amount of help from my colleague Vishal, we managed to get it working using the Draft Process API - the PROCESSES API doesnt seem to work as advertised

will need to look further into that on 16.2.11 testbox - may need one of the 20.x instances to properly work. Agree that the docs and worked examples are in massively short supply, perhaps the new Dev Portal will improve things.

var myTicket; // OTDS Ticket

var WFObject; // global to store the process id between function calls

// load the WF map, in my case the dataid is 3588

Vishal has also posted a similar implementation to the above, and also a PowerShell version at https://appworksdeveloper.opentext.com/awd/forums/questions/22393275#r30882660.

Greg Griffiths · July 5, 2020

@Mario Cano a new thread would have been best as this is a separate topic, but I would not recommend updating the DB as this will breach your OT Support contract. You seem to have an issue saving the WF to the DB, so I would generate the logs and reach out to OT with the THREAD & CONNECT logs, a SysReport and also a copy of your WFMap, it may be that the map needs a little work or you could be missing a patch etc.

Clarkebar2 · July 6, 2020

Hello Ed,

I went through the same head banging experience with starting and monitoring a WF via the CS REST API.
It just a couple of REST calls to create the draft and then start it.

You can then make another call and get the status of the WF.

Regards,

-MC

Ed Davis · July 6, 2020

Thanks a lot everyone...

Looks promising and I will work through this the next couple of days.

Ed

Ed Davis · July 6, 2020

Would anyone have an example for the syntax for updating the form data and attachments.

I see the ask in App Developer from Mahesh but no response.
"1) How can we initiate workflow with form data. you mentioned to use the action as formUpdate but how do we set the form fields."
" 2) How can we get the workflow attachment folder id so we can upload docs while we initiate workflow."

With these methods, I think you would have a good baseline Rest pattern for Workflows

Ed

Vishal_Kashelkar · July 6, 2020

Ed Davis said:

Would anyone have an example for the syntax for updating the form data and attachments.

I see the ask in App Developer from Mahesh but no response.
"1) How can we initiate workflow with form data. you mentioned to use the action as formUpdate but how do we set the form fields."
" 2) How can we get the workflow attachment folder id so we can upload docs while we initiate workflow."

With these methods, I think you would have a good baseline Rest pattern for Workflows

Ed

Okay, I've never implemented this using REST and since REST documentation is not really helpful, I decided to look under the hood and here's what I found (on CS 16.2.4 instance)
1. I dont think you can attach document in workflow using draftprocess API (the implementation is not there in the REST CALL)
2. Let's say you have a workflow (with 1 form - 1 attribute and 1 workflow attribute), In order to update these fields you need to send body field in following format { "draftprocess_id":"{{draftprocess_id}}", "title":"{{$randomWords}}", "action":"formupdate","Values":{"WorkflowForm_1x4x1x2":"value for form attribute","WorkflowForm_2":"workflow attrib value"}}

For form attributes the key format is WorkflowForm_1x4x<form number>x<attribute id> for e.g. WorkflowForm_1x4x1x2
For workflow attribute the key format is WorkflowForm_<attribute id> for e.g WorkflowForm_2

so in a nutshell, though it is possible to update form and workflow attributes during workflow initiation using REST API, I wouldnt recommend it.

Appu Nair · July 6, 2020

Are they using a different method methodology when you bring up a WF map in SmartUI, add a document , add attributes et al and start a workflow I see lots of info in fiddler and network traces in my browser and that is how sometimes when I do not know what to plug in where in REST I resort to . At least on my 16.2.8 I was able to start a workflow and put a desktop file . REST has no real good examples to work with mostly reverse engineering most of the time for me.

Ed Davis · July 6, 2020

Thanks again everyone, I will experiment with all the info I received in the last 24hrs.

Ed

Chris Meyer · July 7, 2020

A few months ago I traced initiating a workflow with the REST API and below are the steps I found. Some of the operations here made their way into the @kweli/cs-rest npm package, which you can read about on my blog.

Here's a rough outline of initiating a workflow with the REST API, which is greatly simplified.

POST: /api/v2/draftprocesses
parameters: {workflow_id: map_id} 

- map_id is the dataid of the workflow map

From the response,

let draftprocess_id = results.draftprocess_id

Then,

GET /api/v1/forms/draftprocesses/update
params: {draftprocess_id:draftprocess_id}

The response is workflowInfo, which gives you the options for setting up the workflow. E.g.,

workflowInfo.data.instructions - instructions
workflowInfo.data.title - title
workflowInfo.data.authentication - true/false, whether authentication is required (i.e., a password must be supplied with the call to initiate the WF)
workflowInfo.data.attachments_on - true/false, whether attachments are permitted
workflowInfo.data.process_id - process id (you'll need this later)

Workflow attributes are in workflowInfo.forms, which contains an array with the forms defined on the "Smart View" tab of the Start step. I don't know if the "Initiate in Smart View" settings needs to be enabled for this to show up. The workflowInfo.forms[index].data objects contains the form values that can be modified and submitted to update the workflow:

PUT /api/v2/draftprocesses/${draftprocess_id}
params: {
        action:"formUpdate", 
        values: formValues
        }

Attachments are a bit tricky since you need to extract the DataID of the attachments folder.

let data_packages  = workflowInfo.data.data_packages
let attachment_pkg = data_packages.find(pkg => pkg.type == 1 && pkg.sub_type == 1)
let attachment_folder_id = attachment_pkg.data.attachment_folder_id

Then use the standard document upload API to upload attachments.

Finally, to initiate the workflow:

PUT /api/v2/draftprocesses/${draftprocess_id}
params: { 
        action: "Initiate",
        comment: comment,
        authentication_info: {
            password: password 
        }
    }

The comment and authentication_info keys are only required if workflowInfo.data.comments_on and workflowInfo.data.authentication keys are true.

That's roughly how I did it. I hope it helps.

Vishal_Kashelkar · July 7, 2020

GET /api/v1/forms/draftprocesses/update
params: {draftprocess_id:draftprocess_id}
The response is workflowInfo, which gives you the options for setting up the workflow. E.g.,

workflowInfo.data.instructions - instructions

workflowInfo.data.title - title

workflowInfo.data.authentication - true/false, whether authentication is required (i.e., a password must be supplied with the call to initiate the WF)

workflowInfo.data.attachments_on - true/false, whether attachments are permitted

workflowInfo.data.process_id - process id (you'll need this later)

Workflow attributes are in workflowInfo.forms, which contains various keys that define the attributes (data type, name, etc). The workflowInfo.forms.data object contains the form values that can be modified and submitted to update the workflow:

How do you get the form package? as you mentioned workflowInfo.forms returns the information about workflow attributes but I cant find information about the attached forms.

Ed Davis · July 7, 2020

I don't see the forms either, only the WF attributes .

In the mean time, I can work with that as the WF attributes can be a proxy for the form attributes.

What is the syntax for setting the WF attribute values?

If I had two attributes "First_Name" aka <WorkflowForm_2> and "Last_Name" aka <WorkflowForm_3>

 action:"formUpdate", 
        values: {{"WorkflowForm_2":"Ed"},{"WorkflowForm_3":"Davis"}}
or
        values: {"WorkflowForm_2":"Ed","WorkflowForm_3":"Davis"}
or Other!

Snippet from /api/v1/forms/draftprocesses/update?draftprocess_id=4404301

"forms": [
        {
            "Columns": null,
            "data": {
                "WorkflowForm_2": null,
                "WorkflowForm_3": null
            },
            "options": {
                "fields": {
                    "WorkflowForm_2": {
                        "hidden": false,
                        "hideInitValidationError": true,
                        "label": "First_Name",
                        "readonly": false,
                        "type": "text"
                    },
                    "WorkflowForm_3": {
                        "hidden": false,
                        "hideInitValidationError": true,
                        "label": "Last_Name",
                        "readonly": false,
                        "type": "text"
                    }
                }

Chris Meyer · July 7, 2020

How do you get the form package? as you mentioned workflowInfo.forms returns the information about workflow attributes but I cant find information about the attached forms.

I'm guessing here... modify the Start Step of your workflow and enable "Initiate with Smart View". Then see if on the Smart View tab of the Start Step you can add the form fields(?). Hopefully these will show up in workflowInfo.forms.

Vishal_Kashelkar · July 7, 2020

Chris Meyer said:

How do you get the form package? as you mentioned workflowInfo.forms returns the information about workflow attributes but I cant find information about the attached forms.

I'm guessing here... modify the Start Step of your workflow and enable "Initiate with Smart View". Then see if on the Smart View tab of the Start Step you can add the form fields(?). Hopefully these will show up in workflowInfo.forms.

Thanks. that works whatever fields I set for smart view appears in the WorkflowInfo.forms.

Vishal_Kashelkar · July 7, 2020

Ed Davis said:


        values: {"WorkflowForm_2":"Ed","WorkflowForm_3":"Davis"}

I guess this should work.

John Simon · July 7, 2020

Nice work Chris!

Appu Nair · July 7, 2020

Double that Nice Work Chris and everyone else. Now in two years, this community will get retired and no one has any clue where to find a snippet

Clarkebar2 · July 7, 2020

Hello Guys,

I believe REST API does not support WF Forms/Form Attributes, only WF Attributes.

You can see how to invoke the WF by watching the Smart UI WF Widget initiate it. The Widget doesn't appear support Forms (and therefore I believe REST doesn't support Forms either).

Once you get the parameters into the WF, regular WF black magic should be able to take you the rest of the way.

The Smart UI also has another WF Status Widget, this Widget uses an undocumented REST call:

/llisapi.dll/api/v2/workflows/status?wfretention=30&kind=Initiated

This will show you that status of all WFs initiated in the last 30 days. The Widget has a few more parameters but I couldn't figure out how to use them. As far as I know, this is the only way in via the REST API to get the WF status.

Regards,

-MC

EDIT:

I will just add one more note, here is how the syntax for how to send in a multi-value WF attribute in via REST:

values: { WorkflowForm_2:[value0_row0,value0_row1], WorkflowForm_3:[value1_row0,value1_row1] }

Hopefully save you a few headaches

Ed Davis · July 7, 2020

Thanks everyone, it's all working great and I don't think the lack of access to the forms will be a hinder to my app as I can set the attributes like a form.

Anyway, thought I would share my working cascading JS calls to round things up. (Attached)
You can change the authentication to whatever needs you have, but I am hitting the API from home.
I have a simple WF with an email step that sends me back the attribute values to confirm it's working.

Clarkebar2 · July 7, 2020

Looks like you got it Ed, the only thing missing is how to do it with an OTDS ticket.

Regards,

-MC

Ed Davis · July 7, 2020

Confirmed.

beforeSend: function(xhr){xhr.setRequestHeader('OTCSTicket', [LL_REPTAG_OTCSTICKET QUOTE /]);},

Ed

Clarkebar2 · July 7, 2020

WebReports has the ticket for sure. The other challenge I had was getting the ticket, for operation outside of OTCS.
All the guides have you trying to get the ticket from OTCS, but that I believe is incorrect.

You have to go to OTDS via REST and authenticate. This will return the ticket and then you can use it in your OTCS REST call.

function authenticate()
{
	var url = "https://myotds.mycompany.local:8443/otdsws/rest/authentication/credentials";
	var password = atob('');
	
	var parameters = { 'userName' : 'Admin', 'password' : password };

	$.ajax({
		contentType: 'application/json',
		type: 'POST',
        url: url,
		data: JSON.stringify(parameters),
		success: function (resp) {
			$("div").data("admin", resp.ticket);
			
			getDraft();
		},
			error: function (xhr) {
			alert(xhr.responseText);
		}
	});
}

Appu Nair · July 7, 2020

Ed Davis said:

Thanks everyone, it's all working great and I don't think the lack of access to the forms will be a hinder to my app as I can set the attributes like a form.

A

Thanks for providing a working sample this is great collaboration

Ed Davis · July 7, 2020

Thanks Clarkbar2, will try this first thing tomorrow and add it to my snippet collection.

Ed

Clarkebar2 · July 7, 2020

Then you will really have the "full" example or starting a WF from outside of OTCS.

Get the ticket from OTDS (notice that OTDS uses application/json unlike OTCS that uses forms for everything).
Anyway, get the ticket from OTDS, then go to OTCS and use the ticket to start your workflow.

From the example you have made, the only thing you are missing is the OTDS ticket getting.

Then you will have made the example of using the WF in a real world scenario.
It is very kind of you to share it as OT is very, very lite on examples.

Regards,

-MC

Vishal_Kashelkar · July 7, 2020

Clarkebar2 said:

The Smart UI also has another WF Status Widget, this Widget uses an undocumented REST call:

/llisapi.dll/api/v2/workflows/status?wfretention=30&kind=Initiated

This will show you that status of all WFs initiated in the last 30 days. The Widget has a few more parameters but I couldn't figure out how to use them. As far as I know, this is the only way in via the REST API to get the WF status.

There are few more workflow REST calls for which I couldn't find any documentation but can be useful for anyone interested

1.This call will get the list of workflows ontime/workflowlate/completed.

GET: api/v2/workflows/status

parameters: {"wfretention": "30", "Kind": "INITIATED"}

- wfretention is the period specified in days. for e.g. 60 would bring you status of workflows initiated in last 60 days.

- Kind is the kind prompt. Accepted values are ( ALL, MANAGER, MANAGED, INITIATOR, INITIATED, SYSTEM)

2. This call will get workflow status count.

GET: api/v2/workflows/status/widget

parameters: {"wfretention": "30", "Kind": "INITIATED"}

- wfretention is the period specified in days. for e.g. 60 would bring you count of status of workflows initiated in last 60 days.

- Kind is the kind prompt. Accepted values are ( ALL, MANAGER, MANAGED, INITIATOR, INITIATED, SYSTEM)

3. This call will get the info for specified initiated workflow .

GET: api/v2/workflows/status/processes/{process_id}

parameters: {"process_id":"12345"}

- process_id is the work id of the initiated workflow.

4. This call will will reassign the workflow step.

POST: api/v2/workflows/status

parameters: {"WORKID":"12345", "SUBWORKID":"12345","TaskID": "1", "NewUserID": "1000" }

- WORKID is the work id of the initiated workflow.

- SUBWORKID is the subwork id of the initiated workflow.

- TASKID is the task id of the intitated workflow.

- NewUserID is the id of the user to whom task needs to be assigned.

Clarkebar2 · July 9, 2020

I have asked OT to convert this Forum post to a KBA in my ticket regarding the WF Status Widget, ticket #4487752

Regards,

-MC

Amardeep_Arora_1 · September 13, 2021

This is some very useful information that is often either difficult to find or not available at all. I can see that all posts for this thread are in connection to initiating a workflow as it should be since the thread title is about this matter.

I have a similar requirement - i.e. to update workflow attribute, but for a workflow that has already been initiated. I will be able to get the process id of the running workflow instance and wondering if this can be used as a query param to a REST call if its available for this purpose. /draftprocesses endpoint used in the forum is for an uninitiated workflow. I see some great examples on /workflows endpoint put together by Vishal (and not been able to find anywhere else by way of documentation) - maybe there is one available here to update an attribute?

Any guidance would be great.

Thanks all

Initiate Workflow from REST

Comments

Categories