PUBLIC

Task Consumption Model

Document Version: 1.0 – 2017-09-14

TCM Provider Implementation Guide

How to implement an OData provider for My Inbox
Content

1 Implementing an OData Provider for My Inbox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1 Task Consumption Model (TCM). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Mandatory Entities and Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 Optional Entities and Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 Sample Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

5 HTTP status codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18

TCM Provider Implementation Guide

2 P UB L IC Content
1 Implementing an OData Provider for My
Inbox

Use this guide to implement your own OData task provider for My Inbox, which is based on the task consumption
model (TCM).

Prerequisites

You need to have the following systems up and running:

● Custom task provider
● SAP Gateway
● My Inbox SAP Fiori app

Context

If you want to receive and execute all your tasks directly in My Inbox, you can now implement your own TCM-
compliant OData service, reachable via a URL, and connect it to your back-end system.

For more information about the TCM, see Task Consumption Model (TCM) [page 5].

TCM Provider Implementation Guide

Implementing an OData Provider for My Inbox P U BL IC 3
This graphic shows how My Inbox is connected via OData to SAP Gateway and then via OData to your task
provider:

Procedure

1. As a basis for the implementation, take a look at the TCM metadata xml document in SAP Note 2304317 .
2. Implement the minimal set of entities and their mandatory properties to manage tasks from My Inbox.
○ Task and TaskSupports
○ TaskDescription
○ TaskDefinition
○ UIExecution

For a brief description of the mandatory entities and properties and how they are represented in My Inbox,
see Mandatory Entities and Properties [page 6].

Note
The listed properties of the entities in the tables are by no means complete. For a complete list of entities
and properties, see the TCM metadata xml document in SAP Note 2304317 .

3. Optional: Implement optional entities, function imports, and complex types to support additional My Inbox
features.
○ DecisionOptions as optional properties (function imports) of the TaskDefinition entity
○ CustomAttribute and CustomAttributeDefinition
○ UserInfo
○ Comment
○ Attachment
○ SubstitutionRule and SubstitutionProfile

TCM Provider Implementation Guide

4 P UB L IC Implementing an OData Provider for My Inbox
 ○ ProcessingLog

For a brief description of the optional entities and properties and how they are represented in My Inbox, see
Optional Entities and Properties [page 9].

Note
The listed properties of the entities in the tables are by no means complete. For a complete list of entities
and properties, see the TCM metadata xml document in SAP Note 2304317 .

4. Implement requests.

For sample requests that you can use with a TCM service, see Sample Requests [page 15].

For error handling methods, see HTTP status codes [page 18].
5. Conduct the following testing activities:
a. Test your implemented OData service.
b. After connecting your OData service to Task Gateway, test your My Inbox with the connected OData
service.

Related Information

Task Consumption Model (TCM) [page 5]

Mandatory Entities and Properties [page 6]
Optional Entities and Properties [page 9]
Sample Requests [page 15]
HTTP status codes [page 18]

1.1 Task Consumption Model (TCM)

The task consumption model is a standard format for describing (workflow) tasks and related entities.

The TCM enables you to harmonize (workflow) tasks across multiple applications and solutions, and makes them
interoperable. It is a standard OData service definition that you must comply with as a task provider.

The TCM is implemented by the Task Gateway Service. For more information, see Task Gateway Service.

TCM Provider Implementation Guide

Implementing an OData Provider for My Inbox P U BL IC 5
2 Mandatory Entities and Properties

This section gives an overview of the mandatory entities with their mandatory properties, a brief description, and
how they are represented in My Inbox.

This graphic shows how the mandatory entities are related to each other:

Note
The listed properties of the entities in the following tables are by no means complete. For a complete list of
entities and properties, see the TCM metadata xml document in SAP Note 2304317 , or refer to the Task
Gateway Service documentation.

Note
The property SAP_Origin is a mandatory property for TCM all entities. You must set it as NA for all entities. It
was introduced in order for the Task Gateway system to differentiate between tasks from different provider
systems. The value NA is automatically replaced by the Gateway before providing the information to My Inbox.

Note
All properties of all entities that are language-dependant, are only exposed in the current language of the
session. The language can be identified by the http headers Accept-Language: en or SAP-Language: E in the
http requests.

Table 1:

Entity and Manda Description Representation in My Inbox

tory Properties and Example

Task Represents a task instance based on the TaskDefinition Entry in task list on the left hand
side, with subject (for ex-
ample: Approve leave
request from John
Smith) and other information.
The user can open the task de-
tails from here.

TCM Provider Implementation Guide

6 P UB L IC Mandatory Entities and Properties
 Entity and Manda- Description Representation in My Inbox

tory Properties and Example

SAP_Origin The SID discriminator For your provider, use NA.

InstanceID The unique ID of the task instance For example T000001

Table 2:

Entity and Manda- Description Representation in My Inbox

tory Properties and Example

TaskDescription Translatable long text of a task that can include HTML code Detail view of a task on the
right hand side, with additional
information on the task, repre-
sented in tabs.

SAP_Origin The SID discriminator For your provider, use NA.

InstanceID The unique ID of the task description UI entity For example TD000001A

Description The actual task description For example: Answer all

leave requests for

John Smith.

Table 3:

Entity and Manda Description Representation in My Inbox

tory Properties and Example

Options Sort, Filter, and Group,

TaskDefinition Definition of a task, in order to sort and filter them, and to display at-
represented as buttons with
tributes; possibility to define categories of tasks in order to group
icons, in footer bar on the bot-
them
tom left.

SAP_Origin The SID discriminator For your provider, use NA.

TaskDefinitionID The unique ID of the task definition For example TDef000001.

TaskName The name of the task definition For example Leave

request for John

Smith

Note
My Inbox expects a TaskDefinition only, when the current user has a task instance with the respective task
definition in the inbox or outbox.

TCM Provider Implementation Guide

Mandatory Entities and Properties P U BL IC 7
Table 4:

Entity and Manda Description Representation in My Inbox

tory Properties and Example

UIExecution Represents the link to the task application UI:

Open Task button in footer bar
● External UI to another application with static URL in a new on the bottom right, or if con-
browser window figured, automatically shown in
● Intent-based URL for UIs that are activated on the SAP Fiori front- the detail view of a task.
end server
For more information, see Configuring Navigation in the SAP Fiori
Launchpad documentation.

SAP_Origin The SID discriminator For your provider, use NA.

InstanceID The unique ID of the task execution UI entity For example TUIEx000001

GUI_Link The URL to navigate to, when opening the task execution UI

TCM Provider Implementation Guide

8 P UB L IC Mandatory Entities and Properties
3 Optional Entities and Properties

This table gives an overview of the optional entities with their mandatory properties, a brief description, and how
they are represented in My Inbox.

Note
The listed properties of the entities in the following tables are by no means complete. For a complete list of
entities and properties, see the TCM metadata xml file in SAP Note 2304317 , or refer to the Task Gateway
service documentation on SAP Help Portal.

Note
The property SAP_Origin is a mandatory property for all TCM entities. You must set it as NA for all entities. It
was introduced in order for the Task Gateway system to differentiate between tasks from different provider
systems. The value NA is automatically replaced by the Gateway system before providing the information to My
Inbox.

Note
All properties of all entities that are language-dependant, are only exposed in the current language of the
session. The language can be identified by the http headers Accept-Language: en or SAP-Language: E in the
http requests.

Table 5:

Entity and mandatory Description Representation in My Inbox

properties and Example

Possible decision options (e.g.

DecisionOptions (func- Decisions, which the user can execute anytime, without display-
Approve and Reject), repre-
tion import) ing the task in the detail view. Based on the implementation of
sented as buttons in the footer
these decisions, specific buttons are displayed.
bar on the bottom left.

SAP_Origin The SID discriminator For your provider, use NA.

InstanceID The unique ID of the decision option For example DO000001

Text A Boolean property indicating whether a comment is mandatory

for a decision to be taken

Nature The values POSITIVE or NEGATIVE indicate whether a decision POSITIVE

has a positive outcome (e.g. an approval) or a negative one (e.g.
a rejection).

TCM Provider Implementation Guide

Optional Entities and Properties P U BL IC 9
Table 6:

Entity and mandatory Description Representation in My Inbox

properties and Example

TaskSupports (complex
The TaskSupports entity transforms the information about
type)
which features of the different Task Gateway entities are sup
ported by the different task providers.

Table 7:

Entity and mandatory Description Representation in My Inbox

properties and Example

CustomAttribute Task-specific information that describes the values for a task,

Information tab
based on the CustomAttributeDefinition.

SAP_Origin The SID discriminator For your provider, use NA

InstanceID The key of the task to which the custom attribute value belongs For example TCA000001

Name The name of the custom attribute

Table 8:

Entity and mandatory Description Representation in My Inbox

properties and Example

CustomAttributeDefini Filter by option in footer bar

Definition of task-specific information
tion
Each task entity has a task definition ID as a foreign key to navi-
gate to a task definition entity. Custom attribute definitions are
metadata about the additional information pertaining to the task
instance environment.

SAP_Origin The SID discriminator For your provider, use NA.

TaskDefinitionID The foreign key to navigate to a task definition entity For example TDefID000001

Name The name of the custom attribute definition

Table 9:

Entity and mandatory Description Representation in My Inbox

properties and Example

UserInfo Information about the user, such as first name, last name, phone
Information tab
number, address, and so on

SAP_Origin The SID discriminator For your provider, use NA.

UniqueName The user ID For example Smith

TCM Provider Implementation Guide

10 P UB L IC Optional Entities and Properties
 Entity and mandatory Description Representation in My Inbox
properties and Example

Address The address of the user including Street, StreetNumber, City,

For example
PostalCode, State, and Country (complex types)
Atlanta Road 10;
Atlanta 01010;
Georgia; United
States

Table 10:

Entity and mandatory Description Representation in My Inbox

properties and Example

Comment Comments about a specific task, created by any user who can
Comment tab, listing all com-
view the task ments (for example, by creator
“Please approve my leave re­
quest.”)

Note
Comments can be read-
only, or directly created in
My Inbox if the functionality
is implemented.

SAP_Origin The SID discriminator For your provider, use NA.

InstanceID The ID of the task to which this comment belongs For example T000001.

ID The ID of the comment For example TCom000001A.

Table 11:

Entity and mandatory Description Representation in My Inbox

properties and Example

Attachment Documents or pictures, attached by the creator or processor Attachments tab, listing all at
tachments

Note
Attachments can be read-
only, or directly created in
My Inbox if the functionality
is implemented.

SAP_Origin The SID discriminator For your provider, use NA.

InstanceID The ID of the task to which this attachment belongs For example T000001.

ID The ID of the attachment For example

TAttach000001A.

TCM Provider Implementation Guide

Optional Entities and Properties P U BL IC 11
Table 12:

Entity and mandatory Description Representation in My Inbox

properties and Example

Information about the task pro-

SystemInfo Represents the task provider system. Each provider will return
vider in the detail view of a task
one single SystemInfo entity. at the top center

SAP_Origin The SID discriminator For your provider, use NA.

SystemAlias The system alias of the provider system

Table 13:

Entity and mandatory Description Representation in My Inbox

properties and Example

Manage my Substitutes button

SubstitutionRule Represents a substitution, either a general one, or for a specific
in the bottom right, and the re-
time range. spective option to define sub-
stitutes

SAP_Origin The SID discriminator For your provider, use NA.

SubstitutionRuleID The substitution rule ID For example SR0000001.

User The ID of the substitute user who will work on the current user's For example User0000028.
tasks when the substitution rule becomes active.

BeginDate The date when this rule starts being valid For example 2015-10-01.

EndDate The date when this rule stops being valid For example 2016-10-31.

Table 14:

Entity and mandatory Description Representation in My Inbox

properties and Example

Option within Manage my

SubstitutionProfile Specific profile according to which a substitution takes place;
Substitutes to define specific
groups types of tasks according to function tasks that are to be executed
by the substitute

SAP_Origin The SID discriminator For your provider, use NA.

Profile The key of the substitution profile representing a group of task For example SP000001.
types for which the substitution rule is applied

Table 15:

Entity and mandatory Description Representation in My Inbox

properties and Example

ProcessingLog History of actions that have been executed on the task, with de
Workflow Log side bar (For ex
tailed information ample, “Employee X has cre­
ated a leave request.”)

12 P UB L IC TCM Provider Implementation Guide

Optional Entities and Properties
 Entity and mandatory Description Representation in My Inbox

properties and Example

InstanceID The ID of the task to which the processing log belongs For example T000001. OrderID

The ID of the order of the processing log For example PL00001

Table 16:

Entity and properties Description Representation in My Inbox and

Example

WorkflowLog History of workflows for a task, with detailed information For example, Richard
Wilson created the
task on 06/14/2017 at
10:46 AM

Check the supporting

documents

InstanceID The ID of the task to which the workflow log belongs For example T000001.

EventOrder The order in which the events have been processed for a work- For example,John Miller
flow
created the task and af-
terwards Denise Smith
completed the task”

ReferenceInstanceID The ID of the task instance for which the event has been trig Not visible in the UI
gered

PerformedBy The unique ID of the agent who performed the action on the For example, ID000001
work item

PerformedByName The name of the agent who performed the action on the work For example, Donna Moore
item started the task

Status Latest status of the work item For example: COMPLETED/

CREATED/IN PROGRESS/
WORKFLOW_STARTED

Timestamp Indication when the event was logged For example, 06/14/2017 at
10:46 AM

Description Description text of the work item For example, Approve leave
request for Julie
Armstrong

Country: USA
City: Palo Alto

TCM Provider Implementation Guide

Optional Entities and Properties P U BL IC 13
Entity and properties Description Representation in My Inbox and
Example

SupportsNavigation Flag that determines whether the user can click the description For example, there is available
link to Approve leave
request for Julie
Armstrong

Result Outcome of the work item. For example: Approved, Rejected

ResultType Nature for the outcome of the work item. For example: Negative (displayed
in Red), Positive (displayed in
Green), Neutral (displayed in
Black)

CreationTimestamp Indication when the workflow was initiated For example, Michael Adams

started the workflow

06/13/2017 at 14:00

EndTimestamp Indication by when the workflow should be completed. For example, Due on

For a completed task, it will be the completion time of the task. 06/15/2017 at 09:20 AM

For an open task, for which a deadline is defined, it is either the

'Latest End' or the 'Requested End'.

PerformedByDetails Navigate to UserInfo entity. This entity provides information For example,
related to the user details for the event.
John Miller
Contact Details

Mobile: +1 610-661-
1000

Phone: +1 610-661-1000
Email:
john_miller@[Link]
m

Company

Name:XXXX

Address: USA, Palo

Alto

14 P UB L IC TCM Provider Implementation Guide

Optional Entities and Properties
4 Sample Requests

This sections provides some sample requests that you can use with a TCM service.

Start application

Table 17:
Method Sample Request

GET TaskCollection?$skip=0&$top=1000&$orderby=CreatedOn%20desc&$filter=((Status%20eq%20%27READY
%27%20or%20Status%20eq%20%27RESERVED%27%20or%20Status%20eq%20%27IN_PROGRESS
%27%20or%20Status%20eq%20%27EXECUTED%27))&$inlinecount=allpa

TaskCollection(SAP__Origin='NA',InstanceID='<to be replaced>')

TaskCollection(SAP__Origin='NA'',InstanceID='<to be replaced>')/Description

TaskCollection(SAP__Origin='NA',InstanceID='<to be replaced>')/CustomAttributeData

TaskCollection(SAP__Origin='NA'',InstanceID='<to be replaced>')/UIExecutionLink

DecisionOptions?SAP__Origin='NA''&InstanceID='<to be replaced>'

TaskCollection(SAP__Origin='NA'',InstanceID='<to be replaced>')/Attachments/$count

TaskCollection(SAP__Origin='NA'',InstanceID='<to be replaced>')/Comments/$count

TaskCollection(SAP__Origin='NA',InstanceID='<to be replaced>')/ProcessingLogs/$count

TaskCollection(SAP__Origin='NA'',InstanceID='<to be replaced>')/TaskObjects/$count

Tasks

Table 18:

Scenario Method Sample Request

Select a task GET TaskCollection(SAP__Origin='NA'',InstanceID='<to be replaced>'')

GET TaskCollection(SAP__Origin='NA'',InstanceID='<to be replaced>')/Description

GET TaskCollection(SAP__Origin='NA'',InstanceID='<to be replaced>')/CustomAttribute

Data

TCM Provider Implementation Guide

Sample Requests P U BL IC 15
Scenario Method Sample Request
GET
TaskCollection(SAP__Origin='NA',InstanceID='<to be replaced>')/UIExecutionLink

GET DecisionOptions?SAP__Origin='NA'&InstanceID='<to be replaced>'

GET TaskCollection(SAP__Origin=''NA',InstanceID='<to be replaced>')/Attachments/

$count

GET TaskCollection(SAP__Origin='NA',InstanceID='<to be replaced>')/Comments/$count

GET TaskCollection(SAP__Origin='NA',InstanceID='<to be replaced>')/ProcessingLogs/

$count

GET TaskCollection(SAP__Origin='NA',InstanceID='<to be replaced>')/TaskObjects/

$count

Open a task TaskCollection(SAP__Origin='NA',InstanceID='<to be replaced>')?$select=Status

Claim a task (func POST Claim?SAP__Origin='NA'&InstanceID='<to be replaced>'

tion import)

Approve a task Decision?SAP__Origin='NA'&InstanceID='<to be replaced>'&DecisionKey='0001'

Forward a task GET TaskCollection(SAP__Origin=''NA',InstanceID='<to be replaced>')/PotentialOwners

POST Forward?SAP__Origin='NA'&InstanceID='<to be replaced>'

Release a task POST Release?SAP__Origin='NA'&InstanceID='<to be replaced>'

Group GET TaskCollection?$skip=0&$top=94&$orderby=PriorityNumber%20asc,CreatedBy-

Name%20asc&$filter=((Status%20eq%20%27READY%27%20or%20Status%20eq
%20%27RESERVED%27%20or%20Status%20eq%20%27IN_PROGRESS
%27%20or%20Status%20eq%20%27EXECUTED%27))&$inlinecount=allpages

Filter GET TaskCollection?$skip=0&$top=1000&$orderby=CreatedOn%20desc&$fil-

ter=((SAP__Origin%20eq%20%27NA%27)%20and%20(TaskDefinitionID%20eq
%20%27TS00100010%27)%20and%20(Status%20eq%20%27IN_PROGRESS
%27)%20and%20Priority%20eq%20%27HIGH%27)&$inlinecount=allpages

Sort TaskCollection?$skip=94&$top=5&$orderby=CreatedByName%20asc&$fil-
ter=((Status%20eq%20%27READY%27%20or%20Status%20eq%20%27RE-
SERVED%27%20or%20Status%20eq%20%27IN_PROGRESS%27%20or%20Status
%20eq%20%27EXECUTED%27))&$inlinecount=allpages

Suspend a task POST Resubmit?SAP__Origin='NA'&InstanceID='<to be replaced>'&ResubmissionDate=da

tetime'2015-10-30T00:00:00'

TCM Provider Implementation Guide

16 P UB L IC Sample Requests
UserInfo

Table 19:

Scenario Method Sample Request

View UserInfo GET UserInfoCollection(SAP__Origin='NA',UniqueName='FRITSCHE')

/TASKPROCESSING;mo;v=2/UserInfoCollection(SAP__Origin='NA',Unique
Name='FRITSCHE')/$value

Substitution

Table 20:

Scenario Method Sample Request

View Substitution
POST SubstitutionRuleCollection
Rule
SubstitutionProfileCollection

/TASKPROCESSING;mo;v=2/UserInfoCollection(SAP__Origin='NA',Unique
Name='MIUSER7')/$value

Add Substitution
SearchUsers?SAP__Origin='NA'&SearchPattern='miuser3'&MaxResults=100
Rule
SubstitutionProfileCollection

SubstitutionRuleCollection (CREATE Entity)

Substitute For

Attachments

Table 21:

Scenario Method Sample Request

Get Attachment POST TaskCollection(SAP__Origin='NA',InstanceID='<to be replaced>')/Attachments

Add Attachment POST /TASKPROCESSING;mo;v=2/TaskCollection(SAP__Origin='NA',InstanceID='<to be

replaced>')/Attachments (POST)

Delete Attachment POST DELETE AttachmentCollection(SAP__Origin='NA',InstanceID='<to be re-

placed>',ID='464F4C333330303030303030303030303445585434303030303030
30303131323332')

TCM Provider Implementation Guide

Sample Requests P U BL IC 17
5 HTTP status codes

If an error occurs while processing the received service request, the TCM OData service returns a suitable error
response along with a corresponding HTTP status code.

Table 22:
HTTP status code Description

400 (Bad
Request) The syntax of the sent request is invalid.

403 (Forbidden) The user who sent the request is not authorized to access the
requested data, or to perform the requested action.

404 (Not Found) The requested object could not be found.

405 (Method Not Allowed) The action to be executed is not supported by the OData serv
ice.

406 (Not Acceptable) The requested object cannot be returned in the specified for-
mat according to the accept headers.

500 (Internal Server Error) An error occurred while processing the request.

501 (Not Implemented) The OData service does not support the requested operation.

TCM Provider Implementation Guide

18 P UB L IC HTTP status codes
Important Disclaimers and Legal Information

Coding Samples
Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system
environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and
completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP
intentionally or by SAP's gross negligence.

Accessibility
The information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a
binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does not
apply in cases of willful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.

Gender-Neutral Language
As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales
person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not
exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.

Internet Hyperlinks
The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not
warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages
caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency
(see: [Link]

TCM Provider Implementation Guide

Important Disclaimers and Legal Information P U BL IC 19
[Link]/registration/
[Link]

© 2017 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any
form or for any purpose without the express permission of SAP SE
or an SAP affiliate company. The information contained herein may
be changed without prior notice.
Some software products marketed by SAP SE and its distributors
contain proprietary software components of other software
vendors. National product specifications may vary.
These materials are provided by SAP SE or an SAP affiliate company
for informational purposes only, without representation or warranty
of any kind, and SAP or its affiliated companies shall not be liable for
errors or omissions with respect to the materials. The only warranties
for SAP or SAP affiliate company products and services are those
that are set forth in the express warranty statements accompanying
such products and services, if any. Nothing herein should be
construed as constituting an additional warranty.
SAP and other SAP products and services mentioned herein as well
as their respective logos are trademarks or registered trademarks
of SAP SE (or an SAP affiliate company) in Germany and other
countries. All other product and service names mentioned are the
trademarks of their respective companies.
Please see [Link]
[Link] for additional trademark information and notices.