Technical Articles
How to assign a processor to a task via API within a project collaboration
Introduction
SAP S/4HANA Cloud for projects, project collaboration (f.k.a SAP Project Intelligence Network) is a cloud-based solution for project collaboration between internal and external project partners. It offers capabilities to share any kind of information and acting as a single source of truth for all project related business information like documents, tasks, issues, … .
SAP S/4HANA Cloud for projects, project collaboration also provides APIs which can be used to integrate with other applications or to extend the core capabilities offered.
In this blog I’ll explain how a processor can be assigned to a project collaboration task by using public APIs.
Business Partner vs. Project Membership
Before we dig into the APIs the difference between a business partner and a project membership have to be understood.
All users and companies which have been invited to a collaboration project are stored in the business partner repository. Once a user is invited to a project and the user accepts the invitation this user becomes a member of the project. The following picture depicts the structure.
Business Partner / Project Membership
Within collaboration projects (Project A, Project B) only the memberships are relevant. In each project users get a unique project specific membership UUID (“projectMembershipId“). If you have the need to handle users within a project the project membership UUID is the one which have to be used. Please consider if you read business objects via GET APIs the project membership ID is also returned attributes like
- modifiedBy,
- createdBy,
-
assignedByPersonId,
-
processorPersonId
Prerequisites
To be able to use public APIs of SAP S/4HANA Cloud for projeccts, project collaboration you have to setup service instances in your BTP accocunt. More details can be found in the blog postĀ How to consume SAP Project Intelligence Network APIs.
Further prerequisites are
- A collaboration project has to be available.
- A task in the project has to be available.
Steps to assign a task processor (user) to a task
- Lookup the project membership UUID for users
- Assign the user as processor to a given task
1. Lookup the project membership UUID for users
Read all project members for a given project can be achieved by the following API call.
https://{{base-url}}/ProjectPartnerService/v1/odata/v2/Users?$filter=projectId eq 'project-uuid'
{{base-url}} | Your url to the public API, which is defined in the API service instance |
project-uuid | UUID of the relevant collaboration project |
Result
<?xml version='1.0' encoding='utf-8'?>
<feed ...
<entry>
...
<content type="application/xml">
<m:properties>
<d:projectPartnerMembershipId>888888a-888a-888a-888a-8888aaa8a8a8</d:projectPartnerMembershipId>
<d:projectMembershipId>1111111a-111a-111a-111a-1111aaa1a1a1</d:projectMembershipId>
<d:userRoleName>Project Manager</d:userRoleName>
...
<d:firstName>Test</d:firstName>
<d:lastName>User 1a</d:lastName>
<d:emailAddress>test.user.1a@sap.com</d:emailAddress>
...
</m:properties>
</content>
</entry>
<entry>
...
<content type="application/xml">
<m:properties>
<d:projectPartnerMembershipId>9999999a-999a-999a-999a-9999aaa9a9a9</d:projectPartnerMembershipId>
<d:projectMembershipId>3333333a-333a-333a-333a-3333aaa3a3a3</d:projectMembershipId>
<d:userRoleName m:null="true"/>
...
<d:firstName>Test</d:firstName>
<d:lastName>User 3a</d:lastName>
<d:emailAddress>test.user.3a@sap.com</d:emailAddress>
...
</m:properties>
</content>
</entry>
</feed>
The project membership ID keeps the relevant person UUID for setting the processor (see step 2).
<d:projectMembershipId>1111111a-111a-111a-111a-1111aaa1a1a1</d:projectMembershipId>
Read a specific project member, in case the email address of the person is known.
https://{{base-url}}/ProjectPartnerService/v1/odata/v2/Users?$filter=projectId eq ‘93856bf4-928c-4ef6-b87e-38ca2cc88f20’ and emailAddress eq ‘test.user.1a@sap.com‘
More details about the Project Partner Service API can be found in the API documentation.
2. Assign the user as processor to the given task
Once the project membership ID of the user is available use this UUID to set the task processor by the following API call
https://{{base-url}}/TaskService/v1/Tasks(task-uuid)/service.TaskServiceV1.Processor
{{base-url}} | Your url to the public API, which is defined in the API service instance |
task-uuid | UUID of the relevant task |
Request body (JSON)
{
"processorPersonId": "1111111a-111a-111a-111a-1111aaa1a1a1"
}
The defined processorPersonId is the project membership ID from test.user.1a@sap.com (see step 1)
More details about the Project Partner Service API can be found in the API documentation.
Summary
- You would have learnt to understand the differences between user in the business partner repository and a project member and how they are linked.
- In addition you may have learned how to set a task processor by retrieving the project membership ID and setting this user as a processor for a project task.
I would like to encourage you to try it out and share your feedback/comments/questions in the comments section of the blog.
Also, for any general queries w.r.t project collaboration, please post your questions in ourĀ community