query, read, create and update cloud for...unnati hasija, baidya nath kumar, 1.0 odata odata service...

ODATA SERVICE

Query, Read, Create and Update

1

CLOUD FOR CUSTOMER –ODATA SERVICE – QUERY, READ, CREATE AND UPDATE

Version Date Completed Author Description/Comment

1.0 12-06-2014 Raghavendra Jadi,

Unnati Hasija,

Baidya Nath Kumar,

1.0 OData

OData service described in this document is based on OData version 2.0.

For more details on OData please refer the link below.

<www.odata.org/>

2.0 Cloud-for-Customer OData Service

In Cloud for Customer (C4C) the OData service is available for accounts, tickets (service request) and

opportunity business objects. Entity Data Model (EDM) of the service can be accessed via the URL

below.

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/$metadata

Note: c4c.svc is the name of the service

2.1 Account OData Service.

The Account OData service makes the data visible on the Account Thing Inspector UI.

Each of the tabs on the C4C UI is modeled as separate entities in the service.

For example, Account Team, Relations or Contacts and Addresses.

2.1.1 Business Context and Use

The OData Service for Account enables you to connect external applications to your SAP C4C system

and to query and read Customer’s data within your system.

This service is relevant if the company wants to access Account or Customer data from external

applications.

Account OData service enables the external application or user to perform the following actions:

Query all Customers or Accounts.

Read Account by key.

For a specific Account you can query the Account Team, Contacts/Relationships, Addresses,

Service Requests or Tickets and Opportunities.

The following entities are made available as separate entities in the EDM:

Account Team

Relationships

Contacts

Addresses

http://www.odata.org/

2

2.1.2 Usage with Examples

The metadata of this service which also called EDM is accessed via the link below.

https://<C4C-tenant>/sap/byd/odata/v1/C4C.SVC/$metadata

Metadata the following information:

Entities

Associations

Navigations

Entity Container (which includes entity sets, association sets and function Imports)

Key for every entity

Complex Types

Every entity has a key which uniquely identifies that entity and several properties with type

definition. Navigations are also defined at the entity level.

EDM contains Complex Type definition for data types like Amount, Quantity and so on.

The URL below is used to query all the accounts in the C4C system.

https://<C4C-tenant>/sap/byd/odata/v1/C4C.SVC/CorporateAccountCollection

2.1.2 (a) Read:

An OData Service for Account can be used to read all the records of Accounts/Customers. This can be

accessed as via the link below:

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/CorporateAccountCollection

Specific Accounts can be read via the URL below.

https://<C4C-tenant>/sap/byd/odata/v1/C4C.SVC/CorporateAccountCollection('<Key>')

Note: <key> is AccountUUID property of the entity.

3

2.1.2 (b) Read with Filters:

For an efficient read, filters can be provided to improve performance.

For example, to view only active accounts: status = 2 (active)

https://<C4C-tenant>/sap/byd/odata/v1/C4C.svc/CorporateAccountCollection?$filter=Status eq ‘2’

Various comparison operators can be used:

eq – Equal to

ne – Not equal to

lt – Less than

le – Less than or equal to

gt – Greater than

ge – Greater than or equal to

OData service for Account supports filtering on following attributes along with $top, $skip options:

Name

Last changed date time

Primary contact’s sorted name

Account ID

Status code

ABC Classification code

Industry sector code

Country code

2.1.2 (c) Read with ‘skip’ and ‘top’:

For example, you can use the following URL to view only top ‘20’ results beginning from the 11th

Account.

https://<C4C-tenant>/sap/byd/odata/v1/C4C.svc/CorporateAccountCollection?$skip=10&top=20

2.1.2 (d) Read with ‘skiptoken’:

An OData service with a $skiptoken system query option, identifies a subset of the entries in the

collection of entries which is defined by skipping the entries until specified UUID. It then starts with

the next UUID entries in the collection.

Example:

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.svc/CorporateAccountCollection?$top=2&skiptoken=<UUID>

2.1.2 (e) Navigations:

The following entities are related entities for Account :

(a) Returns the account team for the account:

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.svc/CorporateAccountCollection('<UUID>')/AccountTeam

(b) Returns relationships for the account

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.svc/CorporateAccountCollection('<UUID>')/AccountRelationship

4

(c) Returns contacts for the account.

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.svc/CorporateAccountCollection('<UUID>')/AccountContact

(d) Returns addresses for the account.

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.svc/CorporateAccountCollection('<UUID>')/AccountAddress

es

(e) Returns the service requests or tickets created by the account

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.svc/CorporateAccountCollection(‘<UUID>’)/ServiceRequest

(f) Returns the opportunities for the account

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.svc/CorporateAccountCollection(‘<UUID>’)/Opportunity

2.1.2 (f) Count:

Returns the count of a collection of entities

Example: https://<C4C-tenant>/sap/byd/odata/v1/C4C.svc/CorporateAccountCollection/$count

2.2 Opportunity OData Service.

An Opportunity OData service makes the data visible on the Opportunity Thing Inspector UI.

Information for this service is made available under each tab like Contacts, Sales Team and so on.

Each tab on the UI is modeled as a separate entity in the service.


OData service for Opportunity enables you to connect external applications to your SAP C4C system

to query and read Opportunity data.

This service is relevant if your company wants to access Opportunity data from external applications.

Opportunity OData service enables the external application or user to perform the following actions:

Query all opportunities.

Read Opportunity by Opportunity UUID.

Read related entities such as, Opportunity querying/reading Products, Contacts, Competitors,

Sales Team, Sales Partners, Involved Parties, Involved Party Contacts, Sales Documents and

Related Opportunities.

The following leading and related entities are made available as separate entities in this service.

Opportunity (Leading)

Products

Contacts

Competitors

Sales Team

Sales Partners

Involved Parties

Involved Party Contacts

Sales Documents

Related Opportunities

5


The following URL is used to query all opportunities in the C4C system.

https://<C4C-tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection

Specific opportunities are read using the URL format as shown below.

https://<C4C-tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')

To query/read items of an opportunity, for example products, sales team, and sales partners and so

on, the URL should be in the following format.

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')/OpportunityProdu

ct

This query fetches all products of an opportunity with the provided UUID.

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')/OpportunityConta

ct

This returns all contacts of an opportunity with the provided UUID.

2.2.2 (a) Read:

Specific Opportunity is read using the URL format as shown below.

https://<C4C-tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')

6


The Opportunity OData supports filtering on following attributes along with $top, $skip options:

ID

ExternalID

AccountID

PrimaryContactID

ProbablityPercent

Status

StartDate

CloseDate

Name

ChangedOn

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/OpportunityCollection?$filter=Status eq '2'

This returns all opportunities with status = 2.

https://<C4C-

tenant>/sap/byd/odata/v1/c4c.svc/OpportunityCollection?$inlinecount=allpages&$skip=0&$top=3&

$filter=Status eq '2'

This returns first 3 opportunities with status = 2 and also shows the count as 3.

Note: Filters on other attributes will still work but $top, $skip or $skiptoken should not be used with

them.


https://<C4C-



This returns first 3 opportunities with status = 2 without skipping any Opportunity. . (Say we have 10

opportunities with ID from 1 to 10 then we get three opportunities with ID equal to 1, 2 and 3)

https://<C4C-



This returns 3 opportunities with status = 2 after skipping first 2 opportunities. (Say we have 10

opportunities with ID from 1 to 10 then we get three opportunities with ID equal to 3, 4 and 5)


https://<C4C-

tenant>/sap/byd/odata/v1/C4C.svc/OpportunityCollection?$top=2&skiptoken=<OpportunityUUID>

This will return first two opportunities after the provided UUID.


https://<C4C-

tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportiunityUUID>')/Account

This will navigate to Account entity from Opportunity.

https://<C4C-tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('

'<OpportunityUUID>')/OpportunityProduct('<LINE>')

7

This returns Product data for a specific Opportunity for the given key (Line).

https://<C4C-tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('

'<OpportunityUUID>')/OpportunityContact(RoleCode='xx',PartyID='yyy')

This returns the Contact data for a specific opportunity which has key(RoleCode and PartyID) value =

‘xxx’ and ‘yyy’.

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')/OpportunityComp

etitor(Role='xx',PartyID='yy')

This returns the Competitor data for a specific Opportunity which has key(Role and PartyID) value =

‘xx’ and ‘yy’.

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')/OpportunitySales

Team(Role='xxxx',PartyID='yyyy')

This returns the Sales Team data for a specific Opportunity which has key(Role and PartyID) value =

‘xxxx’ and ‘yyyy’.

https://<C4C-


Partner('XXXX')

This returns the Sales Partner data for a specific Opportunity which has key(PartyID) value = 'XXXX'.

https://<C4C-


Document(ID='xxxx',OpportunityID='yyy')

This returns the Sales Document data for a specific Opportunity which has key(ID and OpportunityID)

value = xxxx and yyy.

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')/OpportunityRelat

edOpportunity(RelatedOpportunityID='xxx',OpportunityID='yyy')

This returns the Related Opportunity data for a specific Opportunity which has

key(RelatedOpportunityID and OpportunityID) value = xxxx and yyy.

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')/OpportunityInvolv

edParty(RoleCode='2',PartyID='2000')

This returns the Involved Party data for a specific Opportunity which has key(RoleCode and PartyID)

value = 2 and 2000.

https://<C4C-


edParty(RoleCode='2',PartyID='2000')/OpportunityInvolvedPartyContact

This returns all the Involved Party Contacts for an Involved Party.

https://<C4C-


8

edParty(RoleCode='2',PartyID='2000')/OpportunityInvolvedPartyContact(InvolvedPartyID=’xxx’,PartyI

D=’yyy’,OpportunityID=’zzz’)

This returns Involved Party Contact for an Involved Party which has key(InvolvedPartyID, PartyID and

OpportunityID).

This OData service offers backward navigation. For example, it is possible to navigate back to parent

entity from the child entity.

https://<C4C-

tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')/OpportunityProdu

ct('20')/Opportunity

The above URL navigates back from OpportunityProduct having key=20 to parent Opportunity.

Similarly from all the child entities like OpportunityContact,

OpportunityCompetitor, OpportunitySalesTeam, OpportunitySalesPartner, OpportunityInvolvedParty,

OpportunitySalesDocument, and OpportunityRelatedOpportunity, it is possible to navigate back to

the parent entity Opportunity.

2.3 Service Request (Ticket) OData Service.

The Ticket OData service makes the data visible on the Tickets Thing Inspector UI (mainly overview

tab). Additionally Ticket Item and different kind of notes, for example internal notes, reply from

customer notes, reply to customer notes, incident description notes and service response reports

notes are also available.


The OData service for Ticket enables you to connect external applications to your SAP C4C system

and allows you to query, read and write tickets within your system.

This service is relevant if your company wants to access data on tickets from external applications.

Ticket OData service enables the external application/user to

Query all tickets.

Read tickets by its UUID.

Query notes and ticket item.

Create tickets

Update tickets

The following entities are made available as separate entities in this service:

Ticket

Internal notes

Reply from customer notes

Reply to customer notes

Incident description notes

Service response reports notes

Ticket Item

9


The metadata of this service which is also called EDM is accessed via the link below.

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/$metadata

The following URL’s are used to query all tickets in the C4C system.

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection or

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/ServiceRequestCollection

Specific tickets can be Read using the URL format as shown below.

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection('<UUID>')

To query/read items of a Ticket, for example internal notes, ticket item and so on, the URL should be

in the following format.

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection('<UUID>')/InternalNotes

This query fetches all Internal Notes of tickets with the relevant UUID.

https://<C4C-

tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection('<UUID>')/ReplyFromCustomerNotes

This returns all the Reply from Customer Notes of tickets with the provided UUID.

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection('<UUID>')/ReplyToCustomerNotes

This returns all the Reply to Customer Notes of tickets with the provided UUID.

https://<C4C-

tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection('<UUID>')/IncidentDescriptionNotes

This returns all the Incident Description Notes of tickets with the provided UUID.

https://<C4C-

tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection('<UUID>')/ServiceResponseReportsNotes

This returns all the Service Response Notes of tickets with the provided UUID.

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketRequestCollection('<UUID>')/TicketItem

This returns all the Items of tickets with the provided UUID.

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection('<UUID>')/Account

This returns the Account information of tickets with the provided UUID.

10

2.3.2 (a) Read:

OData services for Ticket can be used to read all records of the relevant ticket. It can be accessed via

the URL below:

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection

Since tickets are also called service requests there is a provision to access it as service request. The

URL for this is provided below.

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/ServiceRequestCollection

The Read function can be combined with filters such as, skip, top, skiptoken, orderby, select,

inlinecount and so on to limit the number of records, get count of records, and sort it and so on.

>


An OData service with a $filter System Query option identifies a subset of the entries from the

collection of entries. The subset is determined by selecting only the entries that satisfy the predicate

expression specified by the query option. The OData service for tickets supports filtering on following

attributes along with $top, $skip options:

Status

Priority

ID (Ticket ID)

CustomerID (Account ID)

PartnerID (Account Contact)

CompletionDue

ChangedOn

Description (Name of Ticket)

CompletionDueDateTime

11

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection?$filter=Status eq '2'

This returns all tickets with status = 2.

https://<C4C-

tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection?$inlinecount=allpages&$skip=0&$top=3&$filter

=Status eq '2'

This returns first 3 tickets with status = 2 and also shows the count as 3.

Note: Filters on other attributes will still work but $top, $skip or $skiptoken should not be used with

them.

e.g. https://<C4C-

tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection?$inlinecount=allpages&$filter=WarrantyProduct

eq 'xxx'

This returns all tickets with WarrantyProduct = ‘xxx’ and also shows the number of records returned.


https://<C4C-


=Status eq '2'

This returns first 3 tickets with status = 2 without skipping any ticket. . (Say we have 10 tickets with

ticket number 1 to 10 then we get output as ticket no 1, 2 and 3)

https://<C4C-


=Status eq '2'

This returns 3 tickets with status = 2 after skipping first 2 ticket. (Say we have 10 tickets with ticket

number 1 to 10 then we get output as ticket no 3, 4 and 5)


https://<C4C-tenant>/sap/byd/odata/v1/C4C.svc/TicketCollection?$top=2&skiptoken=<TicketUUID>

This will return first two tickets after the provided UUID.


https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection('<UUID>')/Account

This navigates to Account entity from Ticket entity.

https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection('<UUID>')/InternalNotes

This navigates to Internal notes entity from Ticket entity.

2.3.2 (f) Create and Update Functionality of Ticket

The OData for Ticket supports function such as Create and Update of tickets. This can be utilized via

http POST and PUT methods.

12

Create a Ticket:

OData Service for Ticket supports creating data using http POST method.

The following steps should be followed to create a ticket:

i. Provide the URL as given below.

a. https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection

ii. Provide the XML data for creating tickets and click Send. A sample XML is provided below:

<?xml version="1.0" encoding="utf-8"?>

<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"

xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"

xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"

xml:base="https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/">

<atom:category term="C4C.SVC.Ticket"

scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>

<atom:content type="application/xml">

<m:properties>

<d:Description>demo_create_Ticket</d:Description>

<d:NameLanguage>E</d:NameLanguage>

<d:Type>SRRQ</d:Type>

</m:properties>

</atom:content>

</atom:entry>

Since the function Create cannot return the ID/UUID of created entry correctly, use any of the filter

parameters to retrieve and check the record.

e.g. https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection?$filter=Description eq

'demo_create_Ticket'

Update a Ticket:

OData Service for Ticket supports creating data using http PUT method. For the Update of any Ticket,

the Ticket UUID must be a part of URL and XML being sent.

For updating a ticket, following steps should be used:

i. Provide the URL as given below.

a. https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection(‘<UUID’>)

13

iii. Provide the XML data for creating ticket and click Send. A sample data is provided below:

<?xml version="1.0" encoding="utf-8"?>

<atom:entry xmlns:atom="http://www.w3.org/2005/Atom"

xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"

xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"

xml:base="https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/">

<atom:category term="C4C.SVC.Ticket"

scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>

<atom:content type="application/xml">

<m:properties>

<d:Description>demo_update_Ticket</d:Description>

<d:TicketUUID>UUID</d:TicketUUID>

<d:NameLanguage>E</d:NameLanguage>

<d:Type>SRRQ</d:Type>

</m:properties>

</atom:content>

</atom:entry>

Since update cannot return any data, query the data again to check if it is correctly updated.

E.g. https://<C4C-tenant>/sap/byd/odata/v1/c4c.svc/TicketCollection(‘<UUID’>)

Copyright

© Copyright 2014 SAP AG. 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 AG. The information contained herein may be changed without prior notice.

Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.

Microsoft, Windows, Excel, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation.

IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, System x, System z, System z10, System z9, z10, z9, iSeries, pSeries, xSeries, zSeries, eServer, z/VM, z/OS, i5/OS, S/390, OS/390, OS/400, AS/400, S/390 Parallel Enterprise Server, PowerVM, Power Architecture, POWER6+, POWER6, POWER5+, POWER5, POWER, OpenPower, PowerPC, BatchPipes, BladeCenter, System Storage, GPFS, HACMP, RETAIN, DB2 Connect, RACF, Redbooks, OS/2, Parallel Sysplex, MVS/ESA, AIX, Intelligent Miner, WebSphere, Netfinity, Tivoli and Informix are trademarks or registered trademarks of IBM Corporation.

Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.

Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Oracle is a registered trademark of Oracle Corporation.

UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group.

Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc.

HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C®, World Wide Web Consortium, Massachusetts Institute of Technology.

Java is a registered trademark of Sun Microsystems, Inc.

JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape.

SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP Business ByDesign, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries.

Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects S.A. in the United States and in other countries. Business Objects is an SAP company.

All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary.

These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group 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.