Query, Read, Create and Update CLOUD FOR CUSTOMER ODATA SERVICE QUERY, READ, CREATE AND UPDATE

(1)

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

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

(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

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

2.2.1 Business Context and Use

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

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

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

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

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)

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.

(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-tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')/OpportunitySales Partner('XXXX')

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

https://<C4C-tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')/OpportunitySales 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-tenant>/sap/byd/odata/v1/C4C.SVC/OpportunityCollection('<OpportunityUUID>')/OpportunityInvolv edParty(RoleCode='2',PartyID='2000')/OpportunityInvolvedPartyContact

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

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

2.3.1 Business Context and Use

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

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

(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

(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. 2.3.2 (c) Read with ‘skip’ and ‘top’:

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)

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

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

(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>

(14)

Copyright

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.