This document gives an overview on the capabilities of external integration of SAP Business ByDesign / SAP Cloud for Customer custom solutions developed with SAP Cloud Applications Studio. This document is relevant for you if:

• You are developing (or planning) a custom solution for SAP Business ByDesign or SAP Cloud for Customer with SAP Cloud Applications Studio
• You are searching for means of integrating this solution with an external system.

Figure 1 shows an overview on the options.

Figure 1: Integration scenarios for ByD/SoD with External Systems

The following tables show the availability of the scenanrios:

No	Inbound Calls (ByD/SoD Tenant as Server)	SAP Scenario (SAP BO and SAP UI/web service)	SAP Scenario Extensible?	Custom scenario (SAP BO and custom UI/web services	Custom scenario (custom BO and custom UI/web service)
1	Launch UI via URL	Yes	No	Yes (FP2.6)	Yes (FP2.6)
2	Web service call (REST)	No	No	Yes (FP4.0, SoD only)	Yes (FP4.0, SoD only)
3	Web service call (SOAP)	Yes	Yes (FP2.6) (1)	Yes (FP2.6)	Yes (FP2.6)
4	Receive iForms via Mail-Server	Yes	No	No	No
5	Upload from file share	Yes	No	Yes (FP2.6)	Yes (FP2.6)
6	Receive unformatted mails via mail server	Yes	No	Not applicable	Yes (FP2.6)

Table 1: Inbound sceanrios. Comment: (1): SAP scenario must be prepared for extensibility

No	Outbound Calls (ByD/SoD Tenant as Client)	SAP Scenario (SAP BO and SAP UI/web service)	SAP Scenario Extensible?	Custom scenario (SAP BO and custom UI/web service)	Custom scenario (custom BO and custom UI/web service)
1	Call services from UIs via mashup (RSS/Atom, REST, SOAP)	Yes	Yes (FP2.6) (1)	Yes (FP2.6)	Yes (FP2.6)
2	Custom controls (Silverlight)	Yes	Yes (FP2.6) (1)	Yes (FP2.6)	Yes (FP2.6)
3	Call web services in custom code (SOAP)	Yes	Yes (FP2.6) (1)	Yes (FP4.0)	Yes (FP4.0)
4	Call web services in custom code (REST)	Yes (Customer OD only)	No	Yes (FP4.0)	Yes (FP4.0)
5	Send Forms/iForms via mail, fax, print server	Yes	Yes (FP2.6)(1)	No (frontend print only)	No (frontend print only)
6	Download into file share	Yes	No	No	No
7	Send unformatted mails via mail server	Yes	No	No	Yes (FP2.6)

Table 2: Outbound sceanrios. Comment: (1): SAP scenario must be prepared for extensibility

Terms and abbreviations used in this document:

• BO: Business object
• Studio: SAP Cloud Applications Studio (for SAP Business ByDesign / SAP Cloud for Customer)
• Custom BO: Business object implemented with the studio
• External Integration: Integration of a custom solution (customer-specific or via SAP store distribution) with an external system through web services, mail, …
• ByD/SoD tenant: Tenant on an SAP Business ByDesign or SAP Sales OnDemand system

Help resources used in this document:

• [Studio Library]: SAP Cloud Applications Studio Library: Available in the studio under https://help.sap.com_studio_cloud/
• [PSM Documentation] (FP3.5 and higher): Available in the studio under Help -> View Help -> Public Solution Model
• [Repository Explorer]: (FP4.0 and higher): In the studio, select View -> Other Windows -> Repository Explorer
• Thomas Schneider:  SAP Business ByDesign Studio -Application Development: http://www.sap-press.com/products/SAP-Business-ByDesign-Studio-%E2%80%94-Application-Development.html

Table of Content:

Launch UI via URL

You can launch a UI from a ByD/SoD tenant via URL using an inport of the respective UI.

For OWL-based UIs, the basic URL schema is as follows:

https://<hostname>.<domain>

/sap/byd/nav

?bo_ns=<URL encoded BO namespace like specified in the OBN in-port>

&bo=<URL encoded BO name like specified in the OBN in-port>

&node=<URL encoded node name like specified in the OBN in-port>

&operation=<URL encoded OBN operation like specified in the OBN in-port>

   optional:

&object_key=<URL encoded BO instance key, for example UUID> (note: no “-” separator is allowed and all characters must be upper case)

&key_type=<BO instance type (GDT)>

&param = <any additional flat parameter that is required by the OBN in-port>

Example:

/sap/byd/nav?bo_ns=http%3A%2F%2Fsap.com%2Fxi%2FAP%2FCRM%2FGlobal&bo=Opportunity &node=Root&operation=Open&object_key=00163E01041602DE83D9D26C367E44A1&key_type=APC_V_UUID

For thing-based UIs (see Thing-Based UIs and Custom Solutions in Cloud for Customer), the basic URL schema is as follows:

https://<hostname>.<domain>

/sap/byd/nav

              ?bo=<URL encoded ThingType name>
              &nav_mode=TI  ( identifies the navigation to the thing inspector)
              &param.Key= <URL encoded UUID representation>

Example:

/sap/byd/nav?bo=YCHV8LLCY_PROJECT_TT&nav_mode=TI&param.Key=00163E02944F1ED1B59B2A3517D83F98

To determine the tenant URL (https://<hostname>.<domain>), use the re-use service Context.GetSystemURL().

To determine UUID, use the re-use service this.GetObjectNodeReference().

Example coding:

// get URL, for example to show on the UI or send by mail
var URL =
     Context.GetSystemURL() +
     "/sap/byd/nav?bo=YCHV8LLCY_PROJECT_TT&nav_mode=TI&param.Key=" +
     this.GetObjectNodeReference().UUID.content.ToString();

Availability: FP2.6 (for OWL-based UIs), SoD wave 4 (for thing-based UIs)

Transfer protocol: HTTPS

Authentification: User/password or user certificates

Scope: Launch a ByD/SoD UI (SAP or custom UI), prefill the data of an UI inport

Usage: User to system communication (for example display of a ByD/SoD document, create a ByD/SoD document via UI)

Development process overview:

• Open the ByD/SoD UI and analyze the inports of the UI
• Call the UI using the inport

Documentation: not yet available

Web service call (REST)

You can use REST/OData-based web services of the ByD/SoD tenant for user-to-system or system-to-system communication. SAP supports the OData-Protocol. OData follows many of the principles of REST.  OData provides a uniform interface. This means that you address items in an OData feed (i.e. how to construct URIs), you interact with a service (using HTTP verbs), etc. in the same way across any OData Service, regardless of the data it exposes. For details on the OData protocol, see http://www.odata.org.

REST/OData-based web services are

• implemented with the UI designer in the thing type model on top of SAP BOs or custom BOs
• implemented with the report designer on top of SAP BOs or custom BOs

For a thing type-based REST service, the basic URL schema is as follows:

https://<hostname>.<domain>

/sap/byd/rest/

<name of the work center view> /

<name of the thing type>s

?<paramter list, for example filter, paging, etc.>

Example:

/sap/byd/rest/zcontract_wcf.wcf.svc/zcontracts?$filter=Account eq ‘THOMAS’&$top=1

Availability: FP4.0  and higher – SoD only

Transfer protocol: HTTPS/REST

Authentification: User/password or user certificates

Scope

• Read (query, retrieve) operations on top of a SAP BO or custom BO; write (create, update, delete, action) operations are not supported in FP4.0
• Request and response data type are flat structures and do not contains hierarchies

Usage: User to system communication (for example for native mobile devices)

Development process overview (1): thing type-based REST services

• In the studio select a business object and create a thing type (under “Create Screens”)
• Open the thing type in the UI designer and configure the binding and the navigation for the OData service
• Define the authorization (add the thing type to a work center)

Development process overview (2): report based REST services: To be done

Documentation: not yet available

Example:

https://<server>/sap/byd/rest/<wocview>/<thingtype>?<parameterlist>

Example:

https://qpc-cust905.dev.sapbydesign.com/sap/byd/rest/zcontract_t11_wcf.wcf.svc/zcontract_t11s?$filter=Account eq ‘THOMAS’&$top=1See info on OData for ByDesign:

Web service call (SOAP)

You can use SOAP-based web services of the ByD/SoD tenant for user-to-system or system-to-system communication.

Availability: FP2.6 and higher

Transfer protocol: HTTPS/SOAP

Authentification: User/password or user certificates

Scope

• Multiple read (query, retrieve) and write (create, update, delete, action) operations on top of a SAP BO or custom BO
• Request and response data type can contain hierarchies including to-many multiplicity (for example: header – item – sub-item)

Usage

• System to system communication (for example ByD/SoD tenant to ByD/SoD tenant)
• User to system communication (for example for native mobile devices)

Development process overview

• In the studio select a business object and define a web service with multiple operations. Define the authorization profile (for user-to-system or system-to-system communication(as of FP4.0) )
• Activate the service endpoint and WSDL
• Assign the authorization profile to a user or define the system-to-system communication (communication arrangement, FP4.0)
• Download the generated WSDL and use in a client

Documentation:

• [Studio Library] (FP2.6 and higher): Developer Desktop -> Web Services
• Thomas Schneider:  SAP Business ByDesign Studio -Application Development:  Section External Web Services

Call services from UIs via Mashup

You can use mashup web services to consume an external web service, render the data in a data mashup component and include the mashup component in a UI (SAP UI that is prepared for extensibility or custom UI). Write back to the host UI is possible (SAP UI that is prepared for write-back or custom UI)

Availability: FP2.6 and higher

Transfer protocol: HTTP or HTTPS, SOAP, REST, or RSS/ATOM

Authentification: None, user/password, user certificates, API keys

Scope

• Request and response data type must be simple structures or lists
• Write back is available for a simple structure

Prerequiste: For integration into SAP UIs, SAP must prepare the UI with suitable outports and inports

Usage: User-to-system communication (ByD/SoD UI to external web service)

Development process overview

• In the studio (as of FP3.5) or in the Web Service Authoring view in the Application and User Management work center, define a REST Mashup Web Service (import the external web service definition (WSDL, REST or RSS/Atom URL) and extract/configure the parameters and authentification method)
• In the studio (as of FP3.5) or in the Mashup Authoring view in the Application and User Management work center, define a data mashup that invokes the web service and renders the output
• In the UI designer (extensibility explorer) add the mashup to the screen and configure the port binding

Documentation:

• [Studio Library] (FP2.6 and higher): Developer Desktop -> Mashups
• Thomas Schneider:  SAP Business ByDesign Studio -Application Development Section Adding Mashups to User Interfaces

Custom controls (Silverlight)

You can implement a custom control (in Silverlight) and use Silverlight features for sending/receiving data

Availability: FP2.6

Transfer protocol: APIs (see documentation)

Scope: Launch a native Silverlight component from within the ByD/SoD UI

Usage: User to local system communication

Development process overview:

• In the studio create an embedded UI component (EC) as a “wrapper” for the Silverlight component
• Develop your Silverlight component
• Upload your Silverlight component into the studio and develop the binding
• Integrate the EC into a ByD/SoD UI

Documentation: [Studio Library] (FP2.6 and higher): Developer Desktop -> External Web Service Integration

Call Web Services (SOAP) from Custom Code (BO Integration)

You can call SOAP web services from custom code, for example in business object events and actions.

Availability: FP4.0 and higher

Transfer protocol: HTTP or HTTPS, SOAP

Authentification: None, user/password, user certificates

Scope

• Invocation of SOAP services from business partners (B2B scenarios) or external applications (A2A scenarios)
• Can be integrated in custom BO and BO extensions for SAP BOs (if the SAP BO is extensible)

Usage: System-to-system communication (B2B and A2A scenarios)

Development process overview

• In the studio (as of FP4.0), define an External Web Service Integration, import the external web service definition (WSDL) and activate the project item
• Implement the web service call in your script coding
• In the studio, define a Communication Scenario and select the required web service operations
• In the Application and User Management, Communication Arrangement view, create a new communication arrangement for the new communication scenario, configure the web service endpoint and logon credentials .

Documentation: [Studio Library] (FP4.0 and higher): Developer Desktop -> External Web Service Integration

Example:

BO Definition:

businessobject <BOname> raises WebServiceCoreError, WebServiceContentError {
   message WebServiceCoreError text "Error occured in web service call in communication scenario &1" : LANGUAGEINDEPENDENT_LONG_Name;
   message WebServiceContentError text "&1" : LANGUAGEINDEPENDENT_LONG_Name;

Script code:

var request   : Library::<WSID>.<Operation>.Request; // request structure
var response  : Library::<WSID>.<Operation>.Response;// response structure 
var scenario  = "DemoCS"; // Scenario name
// fill the request
request. <...>
// execute the web service
response = Library::<WSID>.<Operation>(request, "", scenario);
// error handling
// no info at all
if (response.IsInitial()) {
 raise WebServiceCoreError.Create("E", scenario);
}
// fault messages
var faultItems = response.CommunicationFault.Item;
var severity;
if (faultItems.Count() > 0) {
 raise WebServiceCoreError.Create("E", scenario);
 // do not send the complete error stack to the user. Assumption: last message is the most important on.
 raise WebServiceContentError.Create("E", faultItems.GetLast().Note) ;
}
// evaluate the response
response. <...>

Call Web Services (REST) from Custom Code (BO Integration)

You can call REST web services from custom code, for example in business object events and actions.

Availability: FP4.0 and higher

Transfer protocol: HTTP or HTTPS, REST

Authentification: None, user/password, user certificates

Scope

• Invocation of REST services from external applications (A2A scenarios)
• Can be integrated in custom BO and BO extensions for SAP BOs (if the SAP BO is extensible)

Usage: System-to-system communication (A2A scenarios)

Development process overview

• In the studio (as of FP4.0) or in the Application and User Management, Mashup Web Services UI, create a REST mashup Web service in your solution. Choose “Simulate” in the Mashup Web Services view to test it.
• Create a script file for your business object, for example, an action. Define the business logic to call the REST mashup Web service (see example below).

Documentation: [Studio Library] (FP4.0 and higher): Developer Desktop -> Mashups -> Tasks -> Defining the Business Logic to Call a REST Mashup Web Service

Example (script code):

import ABSL;
var serviceID :String;
var parameter : NameAndValue;
var parameters : collectionof NameAndValue;
serviceID = "PW00001";
parameter.Name = "keywords";
parameter.Value = "Rome";
parameters.Add(parameter);
var result = WebServiceUtilities.ExecuteWebService(serviceID, parameters);
var content = result.ResponseContent;
var returnCode = result.ReturnCode;

Formatted Input/Output (Print, Fax, Mail)

Output management comprises all activities related to the output of documents in print, e-mail, or fax format. Form-based documents can be output on an ad hoc basis or as an integrated part of a business process.

Ad hoc output is generated when a user previews a document in Adobe Reader and either prints a paper copy or saves an electronic copy of the document in portable document format (PDF). This type of output does not require any configuration and can take place at any time.

Process-integrated output means that the output of a document is triggered and performed by the system as part of a business process. For example, a purchase order is created by an employee and sent to his or her manager for approval. On approval by the manager, the document is sent automatically to the output channel defined in the output settings of the document. This could be print, e-mail, or fax. Default output settings and output channel and form template rules can be created by key users to define how a particular document is output by the system.

In the studio, only custom ad hoc output scenarios are supported.

ByD supports interactive forms scenarios. Support for custom interactive forms scenario is not available.

Upload from File Share

In ByD/SoD key users can use can XML file to import third-party data from other systems into a business object. You can develop file input scenarios for SAP and custom business objects. Development of a download into a file share scenario is not supported in the studio.

Availability: FP2.6 and higher

Scope and Usage: Upload data into a business object

Development process overview

• In the studio select a business object and define a file upload scenario
• Activate the scenario. A file share is created that you can use to store the files to be uploaded.
• Download the generated WSDL and use it for example in Excel to define the file format
• In the Application and User Management work center, define an upload job (on time or recurring job)

Documentation: [Studio Library] (FP2.6 and higher): Developer Desktop -> Service Integration -> Tasks -> Create XML File Input.

Send/Receive Unformatted Mails via Mail Server

E-mails, fax documents activities are represented by the following business objects:

• EMailActivity: is used to record e-mails as business relevant interactions undertaken between employees on behalf of their enterprise, and its business partners. This business object enables users to track incoming e-mails, as well as outgoing e-mails.
• FaxActivity: is used to record sent or received faxes as business relevant interactions undertaken between employees on behalf of their enterprise, and its business partners. This business object allows the tracking of incoming faxes from business partners, as well as of internally generated, outgoing faxes.

EMailActivity and FaxActivity are released in the public solution model and can be used in custom applications.

The business object Social Media Activity records an interaction undertaken between an employee on behalf of the enterprise and its customer, communicated via social media channels. The Social Media Activity business object is not released (yet).

Availability: FP2.6 and higher

Scope and Usage: Send e-mails or fax documents, access sent or received e-mails

Prerequisite: E-mail and fax has to be set up in the ByD/SoD tenant

Development process overview

• Implement the access to the EMailActivity and FaxActivity in your script coding

Documentation:

• [PSM Documentation] or [Repository Explorer]: EMailActivity, FaxActivity (includes demo scripts for sending/reading EMailActivity, FaxActivity)
• [ByD/SoD Library]: Key User Administration -> Application and User Management -> Input and Output Management -> E-Mail and Fax Queues View -> Business Background -> Configuration: E-Mail and Fax Settings