Initiate Workflow from REST

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.

«1

Comments

  • 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.

  • 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
  • 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
  • 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
    function GetWFDefinition2()
    {
    alert(myTicket);
    var myBody = { workflow_id:3588 };
    $(document).ready(function(){
    var url = baseURL+'/api/v2/draftprocesses';
    $.support.cors = true;
    $.ajax({
    url:url,
    type:"POST",
    crossDomain: true,
    data: myBody,
    dataType:"json",
    headers: { "OTCSTICKET": myTicket },
    success:function(res){
    debugger;
    WFObject = res.results.draftprocess_id;
    alert("success!");
    },
    error:function(res){
    alert("Bad thing happened! " + res.statusText);
    }
    });
    });
    }

    function SetWFTitle2()
    {
    debugger;
    alert(myTicket + ' ' + WFObject);
    var url = baseURL+'/api/v2/draftprocesses/'+ WFObject;
    var title = 'VK';
    var myBody = { "body":'{ "draftprocess_id":"'+WFObject+'", "title":"'+title+'", "action":"formupdate","Values":{}}' };
    $.support.cors = true; 
    $.ajax({
                url:url,
                type:"PUT",
                crossDomain: true,
                data: myBody,
                dataType:"json",
                headers: {OTCSTICKET:myTicket},
                success:function(res){
                            alert("temp map updated");
    },
    error:function(res){
    alert("Bad thing happened! " + res.statusText);
    }
    });
    }

    function InitWF2()
    {
    alert(myTicket + ' ' + WFObject);
    var myBody = { draftprocess_id:WFObject, action:"Initiate" };
    $(document).ready(function(){
    var url = baseURL+'/api/v2/draftprocesses/' + WFObject;
    $.support.cors = true;
    $.ajax({
    url:url,
    type:"PUT",
    crossDomain: true,
    data:myBody,
    dataType:"json",
    headers: { "OTCSTICKET": myTicket },
    success:function(res){
    alert("success!");
    },
    error:function(res){
    alert("Bad thing happened! " + res.statusText);
    }
    });
    });
    }

    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.


  • @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.

  • 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


  • Thanks a lot everyone...

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

    Ed
  • 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
    edited July 6, 2020 #10
    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.

  •    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.
  • Thanks again everyone, I will experiment with all the info I received in the last 24hrs.

    Ed

  • 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.
  • 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"
                        }
                    }
  • 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.

  • 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.
  • Ed Davis said:
    
            values: {"WorkflowForm_2":"Ed","WorkflowForm_3":"Davis"}
    
    I guess this should work.
  • John Simon
    edited July 7, 2020 #19
    Nice work Chris!
  • 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
    edited July 7, 2020 #21

    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


  • 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.



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

    Regards,
    -MC
  • Confirmed.

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

    Ed

  • 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);
    		}
    	});
    }

  • 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 :)
  • Thanks Clarkbar2, will try this first thing tomorrow and add it to my snippet collection.

    Ed

  • 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




  • 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.
  • I have asked OT to convert this Forum post to a KBA in my ticket regarding the WF Status Widget, ticket #4487752

    Regards,
    -MC


  • 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