How to use REST with drafts and workflows | HCL Digital Experience

You can use the REST services for HCL Web Content Manager to create drafts, approve items in a workflow, and move items through different stages of a workflow.

New with HCL Digital Experience 9.5 Container Update 18_1 and higher releases, two new APIs are added to handle Process Now and Remove Workflow from an item functionality.

Creating a draft of an item that does not use a workflow

You can create a draft of items that do not use workflows.

To do that, specify explicitly the draft workflow state in the request entry data. For example, to create a link component as draft: 

HTTP/1.1 POST

http://host:port/wps/mycontenthandler/wcmrest/LibraryLinkComponent
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:wcm="wcm/namespace">
    <wcm:name>linkDraft_E</wcm:name>
    <atom:link atom:rel="library" atom:href="/wps/mycontenthandler/!ut/p/wcmrest/item/d07f0a12-3801-465e-bc20-eaec2cecf5cb"/>
    <category label="Draft" scheme="wcmrest:workflowState" term="DRAFT"/>
</atom:entry>

201 Created

Creating a draft in a workflow

You can use the REST service to create a new draft item. This is equivalent to using the Create Draft icon in the authoring portlet.

A new draft of an item can be created by sending a POST request to the following URI:
/item/item-uuid/create-draft

For example:

HTTP/1.1 POST
http://host:port/wps/mycontenthandler/wcmrest/item/item-uuid/create-draft

201 Created

Moving an item to the next stage

You can use the REST service to move an item to the next stage of a workflow. This is equivalent to using the Next Stage icon in the authoring portlet.

An item can be moved to the next stage by sending a POST request to the following URI:
/item/item-uuid/next-stage

For example:

HTTP/1.1 POST
http://host:port/wps/mycontenthandler/wcmrest/item/<item-uuid>/next-stage

201 Created

Moving an item to the previous stage

You can use the REST service to move an item to the previous stage of a workflow. This is equivalent to using the Previous Stage icon in the authoring portlet.

An item can be moved to the previous stage by sending a POST request to the following URI:
/item/item-uuid/previous-stage

For example:

HTTP/1.1 POST
http://host:port/wps/mycontenthandler/wcmrest/item/item-uuid/previous-stage

201 Created

Approving an item within a workflow

You can use the REST service to move an item to the next stage of a workflow by approving it. This is equivalent to using the Approve icon in the authoring portlet.

An item can be approved by sending a POST request to the following URI:
/item/item-uuid/approve

For example:

HTTP/1.1 POST
http://host:port/wps/mycontenthandler/wcmrest/item/item-uuid/approve

201 Created

Rejecting an item within a workflow

You can use the REST service to reject an item in a workflow. This is equivalent to using the Reject icon in the authoring portlet.

An item can be rejected by sending a POST request to the following URI:
/item/item-uuid/reject

For example:

HTTP/1.1 POST
http://host:port/wps/mycontenthandler/wcmrest/item/item-uuid/reject

201 Created

Restarting a workflow

You can use the REST service to restart a workflow. This is equivalent to using the Restart icon in the authoring portlet.

An item can be restarted by sending a POST request to the following URI:
/item/item-uuid/restart

For example:

HTTP/1.1 POST
http://host:port/wps/mycontenthandler/wcmrest/item/item-uuid/restart

201 Created

Workflow Comments

To ensure that comments are added to workflow stages that require comments, a GET request must be issued to the associated link. This will return an HTML form indicating whether a comment is required.

To add the comment you either submit the form, or perform an HTTP Post request with a content type of text/plain. For example:
HTTP GET /wps/mycontenthandler/wcmrest/item/84e35979-d7c4-429a-b2ab-eb79abc5debc/next-stage 
 Accept: text/html 
 
<html> 
<b>Next Stage</b><br><br> 
<form action="/wps/mycontenthandler/!ut/p/digest!hp5aUN2TU2D-7ziKYRo2-g/wcmrest/item/84e35979-d7c4-429a-b2ab-eb79abc5debc/
next-stage" enctype="multipart/form-data" method="POST"> 
   <label for="comment"><b>*</b>Enter Comment</label> 
   <input id="comment" name="comment" type="text" required/><br> 
   <input type="submit" value="Submit"></input> 
</form> 
</html>

Process Now and Remove Workflow APIs

The Process Now and Remove Workflow from an item functionality are equivalent to their functionality in user interfaces:
Figure 1: Process Now
Figure 2: Remove Workflow

Using the Process Now API

Endpoint
POST request to:
http://host:port/wps/mycontenthandler/wcmrest/item/<(UUID of the content)>/process-now
Sample URL
localhost:10039/wps/mycontenthandler/wcmrest/item/02894453-b03a-4935-8078-5f8ac923a5b0/process-now

Expected Body

The Body can just have the basic Web Content Manager structure or be empty altogether.
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:wcm="http://www.ibm.com/xmlns/wcm/8.0">
</feed>

Expected Headers

LTPA token of the user.

Return Body

The item API for the updated item. This is the same result as when calling .../wcmrest/item/
Sample:
<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:wcm="http://www.ibm.com/xmlns/wcm/8.0">
      <id>wcmrest:09a555cc-05ac-466c-9c8b-80aed68e4f7b</id>
      <title xml:lang="en">dfvdfv</title>
      <summary xml:lang="en"></summary>
      <wcm:name>dfvdfv</wcm:name>
      <wcm:type>Content</wcm:type>
      <updated>2020-05-27T14:36:37.371Z</updated>
      <published>2020-05-27T14:36:35.689Z</published>
      <wcm:created>2020-05-27T14:04:59.407Z</wcm:created>
      <author>
          <wcm:distinguishedName>uid=wpsadmin,o=defaultWIMFileBasedRealm</
wcm:distinguishedName>
          <uri>/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/um/
users/profiles/Z9eAe4JDIJSS6G9P6MMKCJ1P6JMG6NHC6JM4CMPCAMMGCO1CCMR8CNPCGJS06M1</uri>
          <name>wpsadmin</name>
      </author>
      <wcm:owner>
          <wcm:distinguishedName>uid=wpsadmin,o=defaultWIMFileBasedRealm</
wcm:distinguishedName>
          <uri>/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/um/
users/profiles/Z9eAe4JDIJSS6G9P6MMKCJ1P6JMG6NHC6JM4CMPCAMMGCO1CCMR8CNPCGJS06M1</uri>
          <name>wpsadmin</name>
      </wcm:owner>
      <wcm:lastModifier>
          <wcm:distinguishedName>uid=wpsadmin,o=defaultWIMFileBasedRealm</
wcm:distinguishedName>
          <uri>/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/um/users/profiles/Z9eAe4JDIJSS6G9P6MMKCJ1P6JMG6NHC6JM4CMPCAMMGCO1CCMR8CNPCGJS06M1</uri>
          <name>wpsadmin</name>
      </wcm:lastModifier>
      <wcm:creator>
          <wcm:distinguishedName>uid=wpsadmin,o=defaultWIMFileBasedRealm</
wcm:distinguishedName>
          <uri>/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/um/
users/profiles/Z9eAe4JDIJSS6G9P6MMKCJ1P6JMG6NHC6JM4CMPCAMMGCO1CCMR8CNPCGJS06M1</uri>
          <name>wpsadmin</name>
      </wcm:creator>
      <wcm:profile/>
      <wcm:workflow>
          <wcm:publishDate>2020-05-30T00:00:00.000Z</wcm:publishDate>
      </wcm:workflow>
      <link rel="self" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/Content/
09a555cc-05ac-466c-9c8b-80aed68e4f7b" xml:lang="en" label="Read"/>
      <link rel="edit" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/Content/
09a555cc-05ac-466c-9c8b-80aed68e4f7b" xml:lang="en" label="Edit"/>
      <link rel="delete" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/Content/
09a555cc-05ac-466c-9c8b-80aed68e4f7b" xml:lang="en" label="Delete"/>
      <link rel="workflow-stage" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/
WorkflowStage/f89d88b6-b375-4a65-9b99-9befdfc721e1" xml:lang="en" label="Workflow Stage"/>
      <link rel="workflow" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/
Workflow/9ed22ac1-0c5a-4236-9e44-0faefd219d89" xml:lang="en" label="Workflow"/>
      <link rel="access-control" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/ac/
access:oid:Z6QReDeG9E2MQK6LPO6MM06L9O6MMG6MHD6MM4733E4MM07G9OA6IP6O9P83JT623" xml:lang="en" label="Access Control"/>
      <link rel="library" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/Library/
bfa08d5f-1833-4e4e-9455-d23ad24d1179" xml:lang="en" label="Library"/>
      <link rel="parent" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/SiteArea/
9cedbc01-a0a8-4c3f-8051-c9395d13e769" xml:lang="en" label="Parent"/>
      <link rel="versions" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/item/
09a555cc-05ac-466c-9c8b-80aed68e4f7b/versions" xml:lang="en" label="Versions"/>
      <link rel="preview" href="/wps/poc/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcm/
oid:09a555cc-05ac-466c-9c8b-80aed68e4f7b" xml:lang="en" label="Preview"/>
      <link rel="edit-media" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/
Content/09a555cc-05ac-466c-9c8b-80aed68e4f7b" type="application/vnd.ibm.wcm+xml" xml:lang="en" label="Edit Media"/>
      <link rel="content-template" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/
ContentTemplate/3fdeaf06-48d4-4fee-87e7-564d210aee71" xml:lang="en" label="Content Template"/>
      <link rel="elements" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/
Content/09a555cc-05ac-466c-9c8b-80aed68e4f7b/elements" xml:lang="en" label="Elements"/>
      <category scheme="wcmrest:workflowState" term="PUBLISHED" label="Published" xml:lang="en"/>
      <category scheme="wcmrest:favorite" term="false" xml:lang="en"/>
      <content type="application/vnd.ibm.wcm+xml">
          <wcm:content xmlns="http://www.ibm.com/xmlns/wcm/8.0">
                <elements xmlns:atom="http://www.w3.org/2005/Atom">
                    <element name="Body">
                        <title xml:lang="en">Body</title>
                        <type>RichTextComponent</type>
                        <data type="text/html">
                            <![CDATA[<p dir="ltr">dfb</p>
]]>
                        </data>
                    </element>
                </elements>
          </wcm:content>
     </content>
</entry>

Using the Remove Workflow API

Endpoint
POST request to:
http://host:port/wps/mycontenthandler/wcmrest/item/<(UUID of the content)>/remove-workflow
Sample URL:
localhost:10039/wps/mycontenthandler/wcmrest/item/02894453-b03a-4935-8078-5f8ac923a5b0/remove-workflow
Expected Body
The Body can just have the basic Web Content Manager structure or just be empty altogether.
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:wcm="http://www.ibm.com/xmlns/wcm/8.0">
</feed>

Expected Headers

LTPA token of the user.

Return Body

The item API for the updated item. The result is the same as when calling .../wcmrest/item/.
Sample:
<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:wcm="http://www.ibm.com/xmlns/wcm/8.0">
     <id>wcmrest:02894453-b03a-4935-8078-5f8ac923a5b0</id>
     <title xml:lang="en">tedst33</title>
     <summary xml:lang="en"></summary>
     <wcm:name>tedst33</wcm:name>
     <wcm:type>Content</wcm:type>
     <updated>2020-05-27T13:26:07.983Z</updated>
     <wcm:created>2020-05-27T12:19:05.008Z</wcm:created>
     <author>
          <wcm:distinguishedName>uid=wpsadmin,o=defaultWIMFileBasedRealm</
wcm:distinguishedName>
          <uri>/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/um/
users/profiles/Z9eAe4JDIJSS6G9P6MMKCJ1P6JMG6NHC6JM4CMPCAMMGCO1CCMR8CNPCGJS06M1</uri>
          <name>wpsadmin</name>
     </author>
     <wcm:owner>
         <wcm:distinguishedName>uid=wpsadmin,o=defaultWIMFileBasedRealm</
wcm:distinguishedName>
         <uri>/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/um/
users/profiles/Z9eAe4JDIJSS6G9P6MMKCJ1P6JMG6NHC6JM4CMPCAMMGCO1CCMR8CNPCGJS06M1</uri>
         <name>wpsadmin</name>
     </wcm:owner>
     <wcm:lastModifier>
         <wcm:distinguishedName>uid=wpsadmin,o=defaultWIMFileBasedRealm</
wcm:distinguishedName>
         <uri>/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/um/
users/profiles/Z9eAe4JDIJSS6G9P6MMKCJ1P6JMG6NHC6JM4CMPCAMMGCO1CCMR8CNPCGJS06M1</uri>
         <name>wpsadmin</name>
     </wcm:lastModifier>
     <wcm:creator>
         <wcm:distinguishedName>uid=wpsadmin,o=defaultWIMFileBasedRealm</
wcm:distinguishedName>
         <uri>/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/um/
users/profiles/Z9eAe4JDIJSS6G9P6MMKCJ1P6JMG6NHC6JM4CMPCAMMGCO1CCMR8CNPCGJS06M1</uri>
         <name>wpsadmin</name>
     </wcm:creator>
     <wcm:profile/>
         <link rel="self" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/Content/
02894453-b03a-4935-8078-5f8ac923a5b0" xml:lang="en" label="Read"/>
         <link rel="edit" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/Content/
02894453-b03a-4935-8078-5f8ac923a5b0" xml:lang="en" label="Edit"/>
         <link rel="delete" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/Content/
02894453-b03a-4935-8078-5f8ac923a5b0" xml:lang="en" label="Delete"/>
         <link rel="create-draft" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/
item/02894453-b03a-4935-8078-5f8ac923a5b0/create-draft" xml:lang="en" label="Create Draft"/>
         <link rel="change-to-draft" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/
item/02894453-b03a-4935-8078-5f8ac923a5b0/change-to-draft" xml:lang="en" label="Change To Draft"/>
         <link rel="access-control" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/ac/
access:oid:Z6QReDeGHCGJSG6K9D6JM8CGPC2MMG6PPCAJM07GPDGJMK663E2MH57IPC2MQ8CG1" xml:lang="en" label="Access Control"/>
         <link rel="library" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/Library/
bfa08d5f-1833-4e4e-9455-d23ad24d1179" xml:lang="en" label="Library"/>
         <link rel="parent" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/SiteArea/
9cedbc01-a0a8-4c3f-8051-c9395d13e769" xml:lang="en" label="Parent"/>
         <link rel="versions" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/item/
02894453-b03a-4935-8078-5f8ac923a5b0/versions" xml:lang="en" label="Versions"/>
         <link rel="preview" href="/wps/poc/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcm/oid:02894453-
b03a-4935-8078-5f8ac923a5b0" xml:lang="en" label="Preview"/>
         <link rel="edit-media" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/
Content/02894453-b03a-4935-8078-5f8ac923a5b0" type="application/vnd.ibm.wcm+xml" xml:lang="en" label="Edit Media"/>
         <link rel="content-template" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/
wcmrest/ContentTemplate/3fdeaf06-48d4-4fee-87e7-564d210aee71" xml:lang="en" label="Content Template"/>
         <link rel="elements" href="/wps/mycontenthandler/!ut/p/digest!rsWBIQ8xIEvedYpzepFP9w/wcmrest/Content/02894453-b03a-4935-8078-5f8ac923a5b0/elements" xml:lang="en" label="Elements"/>
         <category scheme="wcmrest:workflowState" term="PUBLISHED" label="Published" xml:lang="en"/>
         <category scheme="wcmrest:favorite" term="false" xml:lang="en"/>
         <content type="application/vnd.ibm.wcm+xml">
              <wcm:content xmlns="http://www.ibm.com/xmlns/wcm/8.0">
                    <elements xmlns:atom="http://www.w3.org/2005/Atom">
                          <element name="Body">
                                <title xml:lang="en">Body</title>
                                <type>RichTextComponent</type>
                                <data type="text/html"/>
                          </element>
                    </elements>
              </wcm:content>
       </content>
</entry>