User Experience Insights

Coco Chen

September 6, 2021 9 minute read

[SAP Business Technology Platform on Alibaba Cloud series] Workflow Integrate with Document Management Service

In this post, we will discuss about how to do the integration between Workflow Management service and Document Management Service.

Prerequisites

You’ve subscribed to the Document Management Service, Application Option.
For more information, see Subscribing to Document Management Service, Application Option.
You’ve created an instance of Document Management, Integration Option, and generated a service key using the Cockpit.
For more information, see Creating a Service Instance.
You’ve configured the entitlement of Document Management, Repository option
For more information, see Configure Entitlements and Quotas for Subaccounts.
You’ve installed the CMIS workbench in your local.
Go to CMIS Workbench download page to download it, following the guide to do the environment setup.
You’ve subscribed to the WorkflowManagementSaas, Application Option.
For more information, see Subscribe to SAP Workflow Management.
You’ve created an instance of Workflow, standard plan, and generated a service key using the Cockpit.
For more information, see Creating a Service Instance.
You’ve subscribed to the SAP Business Application Studio (SBAS).

Step 1 – Prepare Document Management repository

This SaaS application (Document Management Service, Application Option) provides a central launch pad UI. You can generate cmis repositories in the launch pad UI and configure destination to make Document Management Integration Option through API to access Document Management Application Option. This type of products must follow OASIS standard.
The SAP Document Management, Integration Option service provides the abilities to create folder, create & update & delete document and other operations follow cmis standard.
Procedure

Go to the SAP Document Management Service application, then navigate into Document Management Service Admin.
Add a new Repository with the ‘Repository type’ is ‘Internal’ to ensure it’s for internal usage.
Configure the destination to integrate with Document Management Integration Option
Follow the guide of Access Document Management Service, Application Option Repository Using API on help portal to configure the integration between Document Management Integration Option and Document Management Application Option.

The new destination looks like below:
Back to Document Management Service application UI page, fill the ‘Service Instance Destination’ with the destination name what we just created in last step.
After the configuration, you can access repositories onboarded via Document Management Service, Application Option through API by connecting to the instance of Document Management Service, Integration Option.

Step 2 – Prepare the document via Document Management Service, Integration Option

In this step, we will access repositories through api to create documents in a specified cmis repository created in previous step
Procedure

Generate access token
A. Get the credentials from the service key:
• ecmservice – url
• uaa – url
• uaa – clientid
• uaa – clientsecret

B. Generate access token in postman using the uaa profiles got above:

There’s 2 ways to create request via api
A. Use CMIS Workbench
– Download and extract CMIS workbench to your local, run workbench.bat in windows environment to open the workbench gui.
– Set the field values in Basic window as shown below:
• URL: Enter the ‘ecmservice – url’ got in previous procedure, the format should be https://<“endpoints” : “ecmservice” : “url”> /browser
• Binding: Browser
• Authentication: OAuth 2.0 (Bearer Token)
– Navigate to Expert window, set the Token as the one generated in procedure 1.
– Load Repositories, CMIS workbench will list all the repositories that Document Management Integration service can get.
– Choose a target repository, it will go to the detail gui to see detailed information.
Go to the target folder which we should put the document.
Using CMIS workbench we can:
– Get the repository information, especially key information such as objectId, repoId…
– Query the repositories, such as folder, documents. Note:
Object ID is the identifier of a folder for a repo, and it can be used in the request to create/delete documents.

B. Use Postman
We can through APIs to execute the admin operations, using the auth token generate in previous step:
– Onboard Repos via connecting your instance of Document Management Service, Integration Option to Document Management service, repository option for file storage.
For more information, see Connect to Document Management Service, Repository Option Using API.
– Access your repository
For more information, see Access Your Repository.
– Create documents into a repo
URI: https://<“endpoints” : “ecmservice” : “url”> /browser/repoId/root/sub-folder
repoId: we can get it via Document Management Service, Application option UI or CMIS workbench
root: root folder is required by default, it doesn’t allow to be modified.
sub-folder: You need to adjust the folder name according to your scenario. If there is not sub-folder under the root folder, root is the end of the URI.
HTTP Method: POST
Authentication: Bearer JWT (JSON Web Token)
Request Parameters:
objectId: it is the unique identification number of a folder in a repo. we can get it via Document Management Service, Application option UI or CMIS workbench
filename: this is the file we want to upload to a folder of a repo
Other parameters are all belong to CMIS standard. You can just follow the CMIS standard to configure your request parameters

After sending requests to create document to the target cmis repository, we can go to the Document Management Application Option UI page or the CMIS workbench to check whether the document is there.

Step 3 – Build the workflow definition

SAP Business Application Studio (SBAS): You shall create workflow project, build workflow module, and deploy the workflow project to the platform.
WorkflowManagementSaas Application provides you with the launch pad UI and it integrates process visibility & workflow service & business rules together. Make sure you subscribed WorkflowManagementSaas Application, created Workflow instance, and generated a service key.
We shall go with below steps to check our workflow definition and create new workflow instance in Workflow Management, Application option.
Procedure

Login in the SBAS to create a workflow
Login into the dev space in the SBAS, then follow the guide to Create a Workflow Module.
The workflow can be designed as below:

Workflow

StartEvent – StartEvent1

SampleOwnerApproval.json

{   
    "ApproversEmail":"Email1@sap.com, Email2@sap.com",    
    "ApproversEmailList":" Email1@sap.com, Email2@sap.com",
    "ApproveFlag":"false",
    "Request":{
        "FirstName":"FirstName",
        "LastName":"LastName",
        "Email":" Email1@sap.com",
        "UserId":"UserId"     
    }
}

ScriptTask – ScriptTask1initialization.js

$.context.approvedEmailHistory = [];

Usertask – Cost Center OwnerScriptTask -CheckApprovers

manageDecisions.js

var ApproversEmailList = $.context.ApproversEmailList;
 //Get who approves the task
 $.context.LastProcessor = $.usertasks.usertask1.last.processor;
 var LastProcessor =  $.usertasks.usertask1.last.processor;
 var approvedEmailHistory = $.context.approvedEmailHistory; 
 /*** For the very first approval, the Request.Email will be added into the approvedEmailHistory*/
 if(approvedEmailHistory.length == 0){
    approvedEmailHistory.push(LastProcessor);
}
/*** if the LastProcessor not in the array then push it*/
approvedEmailHistory.forEach(function(item, index){
    if(item != LastProcessor){
        approvedEmailHistory.push(item);
    }
});
/*** each time a approvers approve the task, just check if all the approvers already completed the approve*/
$.context.ApproversEmailList = ApproversEmailList.split(",").filter(function(item,index){return item != LastProcessor}).join(",");
if(ApproversEmailList.split(",").filter(function(item,index){return item != LastProcessor}).length == 0){
     $.context.ApproveFlag = "true";
}else{
    /**
     * ApprovedEmail != ApproversEmail
     * means that there still has approvers need to approve the task
     * adjust the ApproversEmailList
     */
    $.context.approvedEmailHistory = approvedEmailHistory;
    $.context.ApproveFlag = "false";
}

Gateway – ExclusiveGateway1
RejectApproved
2. Build MTA and deploy the workflow
In the workspace, right click the mta.yaml to ‘Build MTA Project’ , then deploy the mta file to the platform.
3. Check the workflow definition
In the BTP cockpit, login on the Workflow Management SaaS application. In the Monitoring Tools section, enter Monitor Workflows page, we can see the new workflow definition is there.

Step 4 – Create the destination to implement the integration

Now everything is ready except that we still should build the connection between Workflow service and Document Management service.
Go to the cockpit and configure new destination. Just follow the Configure Document Management for Workflow Capability Attachments to configure the destination. repository-id is the repository ID which we can find in either Document Management Service application UI page or CMIS workbench.

Step 5 – Work with Attachments on a Workflow and Task Instance

Before you send request to create new workflow instance:
• You have already built the workflow definition, and within the workflow the User Task is enabled with attachment
• You have already configured the destination for workflow service
• You have already prepared the target cmis repository and configured it with the destination
• You have already created the document in cmis repository via Document Management Integration Option API
• You have already created a workflow service instance and generated a service key.

Procedure

1. Update workflow parameters

Pay attention to that the created workflow service instance should have the necessary scopes. Different action of workflow service has different scope. For much more detail just check the required scopes in Workflow API for Cloud Foundry.

# Update the existing service with expected scopes
cf upate-service <service-name> -c <scope json file>

In case you just create a new workflow instance, you can just update the parameters in the configuration step.

{
    "authorities": [
        "WORKFLOW_INSTANCE_GET",
        "WORKFLOW_INSTANCE_CANCEL",
        "WORKFLOW_INSTANCE_RETRY_RESUME",
        "WORKFLOW_INSTANCE_GET_CONTEXT",
        "WORKFLOW_INSTANCE_GET_EXECUTION_LOGS",
        "WORKFLOW_INSTANCE_SUSPEND",
        "WORKFLOW_INSTANCE_GET_ERROR_MESSAGES",
        "WORKFLOW_DEFINITION_GET",
        "WORKFLOW_INSTANCE_START",
        "WORKFLOW_INSTANCE_UPDATE_CONTEXT"
    ]
}

2. Add attachment information to start a workflow instance

For more information, see Add Attachment Information on Workflow Start.
Note:
– The authorization is similar with the request to create document. Just get the jwt token by accessing the authorization url with the client id and client credential. You can get the client id and client secret from the workflow service key.
– The sample request payload should be prepared according to the design of your workflow:
rootFolder should be fixed with value /root/
groups now in workflow only supports default group
folder is the target folder which your attachment is located
refs/objectId is the object id of the attachment which shall be found via CMIS workbench Query:

Sample workflow payload

{
  "definitionId": "xxxx",
  "context": {
    "ApproversEmail": "xxx@sap.com",
    "ApproveFlag": "false",
    "LastProcessor": "",
    "ApprovedEmail": "",
    "ApproversEmailList": "xxx@sap.com",
    "Request": {
        "FirstName": "first name",
        "LastName": "last name",
        "Email": "xxx@sap.com",
        "UserId": "user id"
    }
  },
  "attachments": {
    "rootFolder": "/root/",
    "groups": {
      "default": {
        "folder": "",
        "refs": [
          {
            "objectId": " objectId"
          }
        ]
      }
    }
  }
}

After sending the request, a new workflow instance with attachment should be created successful, and the receiver will receive the request in workflow my inbox.

With workflow capability, we can have a lightweight integration with the SAP Document Management service. It can handle the binary files completely by the SAP Document Management service (storage, access management, and more) while the workflow capability only maintains the relation between a workflow instance, files, and additional metadata.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.