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

Transcription

1 ODATA SERVICE Query, Read, Create and Update CLOUD FOR CUSTOMER ODATA SERVICE QUERY, READ, CREATE AND UPDATE Version Date Completed Author Description/Comment 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. < 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. 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 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

2 2.1.2 Usage with Examples The metadata of this service which also called EDM is accessed via the link below. 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 (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: Specific Accounts can be read via the URL below. Note: <key> is AccountUUID property of the entity. 2

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) 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 (c) Read with skip and top : For example, you can use the following URL to view only top 20 results beginning from the 11 th Account (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: (e) Navigations: The following entities are related entities for Account : (a) Returns the account team for the account: (b) Returns relationships for the account 3

4 (c) Returns contacts for the account. (d) Returns addresses for the account. es (e) Returns the service requests or tickets created by the account <UUID> )/ServiceRequest (f) Returns the opportunities for the account <UUID> )/Opportunity (f) Count: Returns the count of a collection of entities Example: 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 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 Involved Party Contacts Sales Documents Related Opportunities 4

5 2.2.2 Usage with Examples The following URL is used to query all opportunities in the C4C system. Specific opportunities are read using the URL format as shown below. 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. ct This query fetches all products of an opportunity with the provided UUID. ct This returns all contacts of an opportunity with the provided UUID (a) Read: Specific Opportunity is read using the URL format as shown below. 5

6 2.2.2 (b) Read with Filters: The Opportunity OData supports filtering on following attributes along with $top, $skip options: ID ExternalID AccountID PrimaryContactID ProbablityPercent Status StartDate CloseDate Name ChangedOn eq '2' This returns all opportunities with status = 2. $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 (c) Read with skip and top : $filter=status eq '2' 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) $filter=status eq '2' 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) (d) Read with skiptoken : This will return first two opportunities after the provided UUID (e) Navigations: This will navigate to Account entity from Opportunity. '<OpportunityUUID>')/OpportunityProduct('<LINE>') 6

7 This returns Product data for a specific Opportunity for the given key (Line). '<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. etitor(role='xx',partyid='yy') This returns the Competitor data for a specific Opportunity which has key(role and PartyID) value = xx and yy. 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. Partner('XXXX') This returns the Sales Partner data for a specific Opportunity which has key(partyid) value = 'XXXX'. 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. 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. edparty(rolecode='2',partyid='2000') This returns the Involved Party data for a specific Opportunity which has key(rolecode and PartyID) value = 2 and edparty(rolecode='2',partyid='2000')/opportunityinvolvedpartycontact This returns all the Involved Party Contacts for an Involved Party. 7

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. 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 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 Reply from customer notes Reply to customer notes Incident description notes Service response reports notes Ticket Item 8

9 2.3.2 Usage with Examples The metadata of this service which is also called EDM is accessed via the link below. The following URL s are used to query all tickets in the C4C system. or Specific tickets can be Read using the URL format as shown below. To query/read items of a Ticket, for example internal notes, ticket item and so on, the URL should be in the following format. This query fetches all Internal Notes of tickets with the relevant UUID. This returns all the Reply from Customer Notes of tickets with the provided UUID. This returns all the Reply to Customer Notes of tickets with the provided UUID. This returns all the Incident Description Notes of tickets with the provided UUID. This returns all the Service Response Notes of tickets with the provided UUID. This returns all the Items of tickets with the provided UUID. This returns the Account information of tickets with the provided UUID. 9

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: Since tickets are also called service requests there is a provision to access it as service request. The URL for this is provided below. 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. > (b) Read with Filters: 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 10

11 eq '2' This returns all tickets with status = 2. =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. eq 'xxx' This returns all tickets with WarrantyProduct = xxx and also shows the number of records returned (c) Read with skip and top : =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) =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) (d) Read with skiptoken : This will return first two tickets after the provided UUID (e) Navigations: This navigates to Account entity from Ticket entity. This navigates to Internal notes entity from Ticket entity (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. 11

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. 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=" xmlns:m=" xmlns:d=" xml:base=" <atom:category term="c4c.svc.ticket" 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. 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. <UUID >) 12

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=" xmlns:m=" xmlns:d=" xml:base=" <atom:category term="c4c.svc.ticket" 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. <UUID >) 13

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