PUBLIC

Task Consumption Model

Document Version: 1.0 2016-07-28

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

5 HTTP status codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

PUBLIC TCM Provider Implementation Guide

2 2016 SAP SE or an SAP affiliate company. All rights reserved. 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].

Note
If your provider is ABAP based, then it is more efficient to implement it as described in this SCN article .

If your provider is not ABAP based, then we recommend to implement it via the TCM-compliant OData service
as described in this document.

TCM Provider Implementation Guide PUBLIC

Implementing an OData Provider for My Inbox 2016 SAP SE or an SAP affiliate company. All rights reserved. 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

PUBLIC TCM Provider Implementation Guide

4 2016 SAP SE or an SAP affiliate company. All rights reserved. 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 14].

For error handling methods, see HTTP status codes [page 17].
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 14]
HTTP status codes [page 17]

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 PUBLIC

Implementing an OData Provider for My Inbox 2016 SAP SE or an SAP affiliate company. All rights reserved. 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.

PUBLIC TCM Provider Implementation Guide

6 2016 SAP SE or an SAP affiliate company. All rights reserved. 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

TaskDefinition Definition of a task, in order to sort and filter them, and to display at Options Sort, Filter, and Group,
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 PUBLIC

Mandatory Entities and Properties 2016 SAP SE or an SAP affiliate company. All rights reserved. 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
on the bottom right, or if con
External UI to another application with static URL in a new
figured, automatically shown in
browser window
the detail view of a task.
Intent-based URL for UIs that are activated on the SAP Fiori front-
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

PUBLIC TCM Provider Implementation Guide

8 2016 SAP SE or an SAP affiliate company. All rights reserved. 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 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 5:

Entity and mandatory Description Representation in My Inbox

properties and Example

DecisionOptions (func Decisions, which the user can execute anytime, without display Possible decision options (e.g.
tion import) ing the task in the detail view. Based on the implementation of Approve and Reject), repre
these decisions, specific buttons are displayed. sented as buttons in the footer
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 PUBLIC

Optional Entities and Properties 2016 SAP SE or an SAP affiliate company. All rights reserved. 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 Definition of task-specific information Filter by option in footer bar

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

PUBLIC TCM Provider Implementation Guide

10 2016 SAP SE or an SAP affiliate company. All rights reserved. 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
ments (for example, by creator
view the task
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 PUBLIC

Optional Entities and Properties 2016 SAP SE or an SAP affiliate company. All rights reserved. 11
Table 12:

Entity and mandatory Description Representation in My Inbox

properties and Example

SystemInfo Represents the task provider system. Each provider will return Information about task pro
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

SubstitutionRule Represents a substitution, either a general one, or for a specific Manage my Substitutes button
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

SubstitutionProfile
Specific profile according to which a substitution takes place; Option within Manage my
Substitutes to define specific
groups types of tasks according to function
taks 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 Task History tab (for example
Employee X has created a
tailed information
leave request.)

PUBLIC TCM Provider Implementation Guide

12 2016 SAP SE or an SAP affiliate company. All rights reserved. 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

TCM Provider Implementation Guide PUBLIC

Optional Entities and Properties 2016 SAP SE or an SAP affiliate company. All rights reserved. 13
4 Sample Requests

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

Start application

Table 16:
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 17:

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

PUBLIC TCM Provider Implementation Guide

14 2016 SAP SE or an SAP affiliate company. All rights reserved. Sample Requests
 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 PUBLIC

Sample Requests 2016 SAP SE or an SAP affiliate company. All rights reserved. 15
UserInfo

Table 18:

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 19:

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 20:

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')

PUBLIC TCM Provider Implementation Guide

16 2016 SAP SE or an SAP affiliate company. All rights reserved. Sample Requests
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 21:
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 PUBLIC

HTTP status codes 2016 SAP SE or an SAP affiliate company. All rights reserved. 17
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 wilful 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: http://help.sap.com/disclaimer).

PUBLIC TCM Provider Implementation Guide

18 2016 SAP SE or an SAP affiliate company. All rights reserved. Important Disclaimers and Legal Information
TCM Provider Implementation Guide PUBLIC
Important Disclaimers and Legal Information 2016 SAP SE or an SAP affiliate company. All rights reserved. 19
go.sap.com/registration/
contact.html

2016 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 http://www.sap.com/corporate-en/legal/copyright/
index.epx for additional trademark information and notices.