SAP Analytics Cloud, SAP HANA Cloud

SAP Analytics Cloud Embedded Edition Best Practices & Sample Scripts for Administration

This is an essential article for anyone planning to use the Embedded Edition of SAP Analytics Cloud.

The Embedded Edition is a slimline version of the regular Enterprise Edition meaning the only connectivity is ‘live’ and only to SAP HANA on SAP Cloud Platform. I describe several other important differences between the two editions and what it means for you from an implementation perspective. It means I’ve created best practices that is particular to this Embedded Edition so that you can avoid unnecessary surprises. I also share a bunch of sample scripts that implement the entire ‘administration’ API saving you a significant effort. The samples come with a comprehensive user guide and detailed step-by-step instructions. It is an ideal resource for anyone setting up the Embedded Edition.

What are the business benefits and use-cases?

This article and the associated sample scripts eases your adoption of the Embedded Edition of SAP Analytics Cloud since

  • all the key differences are highlighted and what this means in practical terms and best practices to avoid surprises
  • no need to spend time developing code or trying to understand how the ‘administration’ API works, all that has been done for you.

This article is suitable for all use-cases that use the Embedded Edition of SAP Analytics Cloud, but in particular its focus is on the administration aspects, such as security, SAML, life-cycle management, general service administration etc.

Sample Scripts for Administration

A key difference is the service can only be managed via an API since you’re not allowed to be the ‘System Owner’ and you don’t have access to the same system administration user interface as you do with the Enterprise Edition.

To dramatically speed up your adoption I’ve shared a whole bunch of sample scripts. It means there is no need to:

  • Understand how the API works
  • Develop or write any code

Instead

  • All the hard work and thinking has been done for you
  • Use sample scripts, developed as Postman Collections, which are freely available
  • Every endpoint of the API has been implemented

Meaning, if you’re happy to use Postman then:

  • There’s no need to develop or write any code
  • Just use the samples provided
  • You should find no reason to alter or extend the samples, everything is covered!

Samples consist of

  • 18 samples (Collections)
  • Over 10,000 lines of code
  • 1 ‘Scenario’ for initial security setup of teams, users and roles for use with the SCIM API samples, again developed by me

I’ve encapsulated intelligence into the scripts to ensure the API calls are always valid in addition to managing all the sessions and errors etc. I’ve made everything as easy for you as I can. For example, the sample scripts come with example data files that drive the scripts and these are tailored for this Embedded Edition. There’s even a ‘Scenario’ that uses my other SCIM API Sample Scripts that sets up the security of teams, roles and users just for this Embedded Edition. It means you don’t need to try and work it out for yourself, you just follow the detailed step-by-step instructions to run the scripts.

Best Practices

The API introduces a few subtle implications compared to the user interface and so I’ve shared these insights and a bunch of best practices so you can avoid any surprises. In addition to the sample scripts, I’ve also shared some important and previously undocumented items. To give you an idea they include:

  • How to use teams and why you should avoid team folders
  • Things you need to do before creating teams
  • Why you should create ‘concurrent’ users as ‘named’!
  • The differences for SAML SSO and what you can and can’t do compared to the Enterprise Edition
  • How to manage connections in the landscape to ensure consistency of connection ids (the API can’t edit a connection, only add or delete them)
  • Full documentation of five predefined embedded roles – the official documentation provides the names of two
  • Full list of all the ‘system administration’ configuration options and their default settings

Overview of Embedded Edition

Basic introduction

User interface with the most powerful privileges

SAP Analytics Cloud Embedded Edition

  • Designed for embedding into other applications
  • Simplified, cut-down edition compared to the Enterprise Edition
  • Simplified user interface with connectivity only to SAP HANA databases on SAP Business Technology Platform on Cloud Foundry environment
    • Means only ‘live’ model connections are supported
    • Planning and acquired data models are not supported
  • Fully managed via the API
    • You cannot create new connections, nor perform any system administration tasks though the user interface
    • Instead, these must be performed via the API
    • The only form of management via the user interface is to manage teams:
      • creating/deleting team and adding/removing users from those teams

API Overview

API’s available for both Enterprise and Embedded Editions:

  • Access and Modify Stories and Story Metadata
  • Open Story URL API
  • User and Team Provisioning SCIM API

API’s available only for Embedded Edition:

  • Managing, Configuring, and Monitoring the SAP Analytics Cloud Tenant API
  • The API is the only way to configure the tenant/service

Managing, Configuring, and Monitoring the SAP Analytics Cloud Tenant API

  • The API enables:
    • Creating and deleting OAuth Clients, Trusted IdPs and Live Connections
    • Resetting the Inconsistent Status should it be necessary
    • Displaying the SAML metadata, so allowing you to setup SAML SSO
    • Configuring custom Identity Provider(s)
    • Updating the list of Trusted Origins and all other system configurations options
  • The API doesn’t cover the entire configuration compared to the user interface of the Enterprise Edition
    • For example, its not possible to configure:
      • R Configuration
      • System Event Notifications
      • Connection Notifications
      • Email Server Configuration
      • Default Appearance (Logo, Home Screen Setting, Tiles)
      • Catalogue

Implementation variances for Embedded Edition

  • Broadly, Embedded Edition follows all the best practices as for Enterprise Edition, with a few exceptions
  • These are discussed in this document and presented as best practices so you can avoid unnecessary surprises
  • In summary they are:
    1. Create teams manually without a team folder
    2. Before creating any teams enable the business toggle IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS (same as for Enterprise Edition)
    3. Create users as regular ‘named users’, even though your license is for ‘concurrent sessions’
    4. A few differences in how SAML SSO is setup:
      • Arguable easier than Enterprise Edition
      • Though there’s no option for dynamic user creation
    5. Create connections with the same consistent name across all environments (development and production etc.)
      • Rather than transporting connections to the change them to point to a different data source
      • Since you can not edit a connection via the API, only create or delete them

Sample Scripts

  • Although the API is the only way to configure the tenant/service, there is no need to:
    • Understand how the API works
    • Develop or write any code
  • Instead
    • All the hard work and thinking has been done for you
    • Use sample scripts, developed as Postman Collections, which are freely available
    • Every endpoint of the API has been implemented
  • Meaning, if you’re happy to use Postman then:
    • There’s no need to develop or write any code
    • Just use the samples provided
    • You should find no reason to alter or extend the samples, everything is covered!
  • Samples consist of
    • 18 Samples (Collections)
    • Over 10,000 lines of code
    • 1 ‘Scenario’
      • For initial security setup of teams, users and roles for use with the SCIM API samples by the same author

Comparison between Enterprise and Embedded Editions

Roles, Teams and Users

Roles

Roles cannot be

  • added, removed or amended

Instead 5 predefined roles are provided:

  • PROFILE:sap.epm:Embedded_BI_Content_Admin;
  • PROFILE:sap.epm:Embedded_BI_Content_Viewer;
  • PROFILE:sap.epm:Embedded_BI_Content_Editor;
  • PROFILE:sap.epm:Embedded_BI_User;
  • PROFILE:sap.epm:Embedded_BI_Admin

Definitions for each are documented in the appendix of this article

Regular Best Practice applies

  • Don’t assign users directly to roles, instead assign them to teams and put the teams in roles
    • Though an exception applies in the initial setup – see later

Teams

Teams can be

  • Created and managed
  • Both manually via the User Interface and via the SCIM API

As expected you may:

  • Add and remove users to/from teams
  • Map teams to SAML attributes (for dynamic team assignment)

However

  • Team folders cannot be accessed or managed in anyway
  • This isn’t a general problem as public folders can be used instead (and doing so has at least one benefit over team folders since team folder permissions cannot be updated via the API, even if they where accessible)

Team folders

Create teams without the team folder – de-select this option
  • Given team folders are inaccessible (they are ‘hidden’) it’s a good idea not to create them when creating a team
  • If the team folder is created, its not a problem per se, except…
  • The SCIM API that creates teams will always create a team folder even if you don’t want one
    • The feature to de-select the team folder creation was added after the API was first made available
  • Having a ‘hidden’ team folder could be problematic if you:
    1. Create a team with a team folder
    2. Delete the team (leaving the team folder since there’s no way to delete it)
    3. Create the team, with a team folder, again and use the same name as before
  • Step 3 would fail, as a team cannot be created if the team folder (with the same name) already exists

Best Practices for Team folders

  • To avoid the problem described above: create teams manually via the user interface
  • Create the team without the team folder
    • De-select the button shown
  • But, before creating any teams log a Support Incident with SAP Product Support and ask for the business toggle IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS to be turned on
    • Mention SAP KBA 2857395 and share SAP Analytics Cloud Service URL in the incident
    • This will then mean any teams created manually can also be managed via the API
  • You could allow team folders to be created, when teams are created, but you’ll have to accept that deleting a team means you can’t re-create it with the same name via the API. You would have to create the team via the user interface and de-select the ‘create a folder’ option, or give the team folder a different name
    • Read the blog mentioned above to avoid another gotcha when IMPLEMENT_WORKAROUND_FOR_SCIM_GROUPS has not yet been enabled, but you then want to manage teams via the API having created them manually

Users

150 concurrent sessions per tenant
Menu-Security does not provide an option to manage users

Users can be

  • created and managed only via the SCIM API
  • they cannot be managed via the user interface

License

  • SAP Analytics Cloud Embedded Edition is provided with 150 concurrent sessions
  • Though, perhaps confusingly, all users should be created a regular ‘named user’
  • It means the user property ‘isConcurrent’ must be ‘false’ and not ‘true’
    • Technically speaking ‘isConcurrent’ is only applicable for the Enterprise Edition Business Intelligence concurrent session license. This is the Embedded Edition and so this isn’t applicable

System Owner

  • Once you have created your own SAP Analytics Cloud Embedded Edition tenant a single ‘system owner’ user will have been provisioned for you
  • You are prohibited from:
    • using this user
      • its only provisioned as the service has to have a System Owner
    • becoming the system owner
  • The user is a ‘dummy’ system owner and no-one can login as this user

SAML SSO

Comparison between Enterprise and Embedded Editions

  • Like the Enterprise Edition, the Embedded Edition does allow:
    • Teams to be mapped to users via SAML attributes
  • Unlike Enterprise Edition, the Embedded Edition does allow:
    • The Custom Identity Provider configuration to be changed without the need to revert back to the default Authentication method
      • It means, for example, switching from ‘email’ to ‘userid’, or ‘userid’ to ‘custom’ can be achieved in one step and not two
  • Unlike Enterprise Edition, the Embedded Edition does not allow:
    • Dynamic user creation
    • Users to be mapped to roles via SAML attributes
      • there is no access to Menu-Security-Roles interface
      • so use the Best Practice of assigning Users to Teams, and Teams to Roles
    • Custom Identity Provider to be removed
      • It means once set you cannot revert back to the default Authentication method

Life-cycle Management

Comparison between Enterprise and Embedded Editions

  • Best Practices with the Enterprise Edition
    • In a landscape supporting multiple SAP Analytics Cloud Services each using a different data source, you would create the connection once, transport that connection and then update that connection in the target
    • This will respect the connection ID across the landscape, but allow for different environments to connect their respective data sources
  • Best Practices with the Embedded Edition
    • The API does not allow connections to be edited, they can only be added or deleted
    • You could manually update a model (having transported it there from the source) in the target to use a different connection. However, this is prone to human error
    • Thus, it is preferred, to create the connection with the same id in the other environments, as in the source. This is possible, unlike almost all other objects! The ‘id’ is derived from the ‘name’. So be sure to create the connections, in all environments, with the same name. This will mean you can transport models and they will use the same connection id and each will point to their respective data source

Sample Scripts Overview

Sample Scripts Overview
  • Test and Auto Configure Postman Environment
    • Embedded 701-Test Tenant Environment Setup
    • Embedded 706-Auto Configure Postman Environment for SCIM
    • Embedded 707-Auto Configure Postman Environment for Modelling
    • Embedded 708-Auto Configure Postman Environment for Story Listing
  • Display and check whole system configuration
    • Embedded 711-E-Display & Check System Configuration
  • Express setup
    • Embedded 721-E-SCIM Express setup (based on this Environment)
    • Embedded 723-E-Delete OAuth Client (based on this Environment)
  • General Administration
    • Embedded 731-E-Reset Inconsistent state
    • Embedded 732-E-Display SAML metadata
    • Embedded 733-Fj-Configure Custom IdP
    • Embedded 734-Fj-Update System Configuration
    • Embedded 735-Oarr-Fj-Update Trusted Origins
    • Embedded 741-Fcj-Add OAuth Client
    • Embedded 742-Fcj-Add Trusted IdP
    • Embedded 743-Fj-Add Live Connection
    • Embedded 751-Fcj-Delete OAuth Client
    • Embedded 752-Fcj-Delete Trusted IdP
    • Embedded 753-Fj-Delete Live Connection

Getting Started

  • The ‘721-E-SCIM Express setup’ performs initial setup and is ideal for first time administrators
    • Updates the Content Namespace and creates an OAuth client so you can add users with the SCIM API sample scripts
    • No configuration files to update, just press run!
  • The ‘Scenario E01’ is series of 7 steps that
    • Creates a ‘setup’ user (so you can login to the user interface of SAP Analytics Cloud with full admin rights)
    • Creates 5 teams and assigns each team to one of the 5 embedded roles
    • Re-assigns the ‘setup’ user to use the team to inherit admin role (rather than have the role directly assigned, i.e. adopting best practice)
    • Provides a data file so you can add users into the right teams
  • Configuring SAML SSO
    • 2 sample scripts do this for you
    • Detailed step-by-step instructions include the process of ‘JSON encoding’ the metadata file
  • Follow the User Guide for detailed step-by-step setup instructions
    • Comprehensive 75 page guide
    • Each script fully documented
  • The configuration order is very flexible
    • Configuring Custom Identify Provider and SAML SSO can be done, either before or after users are added
      • Though typically best to do it before too many users are added

A few script highlights

Script: Embedded 711-E-Display & Check System Configuration

  • Perfect for documenting or displaying the current configuration of the whole system configuration
  • Postman Tests show what has or hasn’t been configured
    • Not all tests need to pass, for example ‘Has 1 Trusted IdP’ is only needed for ‘server-to-server communication’ etc.
  • Console log shows full system configuration
    • (plus any parameters that have changed from the default)
    • Complete list of OAuth Clients, Trusted IdP, Live Connections, SAML Setup and more..
    • Warns/errors potential issues

Script: Embedded 734-Fj-Update System Configuration

[
    {
        "file_SystemConfig": [
            {
                "name": "MAX_BW_DRILL_LEVEL",
                "value": "5"
            },
            {
                "name": "NR_PARALLEL_SESSION_FOR_BW",
                "value": "0"
            }
        ]
    }
]
  • Updates System Configuration
    • Uses a simple configuration file (example above)
    • Sample configuration files provided – includes ‘default’ settings for all parameters
  • Table (below) shows all possible parameters with their default settings
    • Setting with a null/undefined value cannot be unset, once set
      • (SAP internal reference FPA45-7610)
Configuration Default Value
MOBILE_REFRESH_ON_OPEN  false
PM_URL_TP_IDP   
COMMENT_EMBEDDED  false 
MOBILE_REMOTE_SAFARI_IDP_URL  https:// 
COMMENTS_MODEL_DIM_MEMBERS  50000 
USER_CONTENT_TRANSLATION  false 
TENANT_CURRENCY_SUBTITLE  false 
SAML_USER_PROFILE_URL   
SESSION_KEEP_ALIVE_SECONDS   
DELETED_FILES_EXPIRY_DAYS  30
REVERSE_PROXY_HOST   
EXTERNAL_AVATAR_WHITELIST   
MAX_BW_DRILL_LEVEL 
FDE_BATCH_WAITING_TIME  1000 
ENABLE_PERSONAL_DATA_PROMPT  false 
NR_PARALLEL_SESSION_FOR_BW 
MOBILE_REMOTE_IDP_URL  https:// 
ENABLE_ON_PREMISE_FILE_EXPORT  false 
TENANT_METRIC_NO_DATA_FORMAT   
ALLOW_SCHEDULE_PUBLICATION  true
AR_SESSION_TIMEOUT_V2  3600
MOBILE_DEFAULT_FILTER 
DEFAULT_APP 
COMMENTS_PER_MODEL_LIMIT  3000 
MOBILE_REMOTE_SAFARI_SAML  false 
TENANT_NO_DATA_FORMAT   
BW_RESPECT_VIZ_DEFAULTING  false 
TENANT_CURRENCY_FORMAT   
BROWSER_CACHE_STORAGE_TIME 
EXPORT_PACKAGE_SIZE  50000 
DISABLE_MOBILE_APP_PASSWORD  false 
ENABLE_ON_PREMISE_FILE  false 
ALLOW_SHARING_TO_ALL_USERS  true 
PREDICTIVE_BI_FORECAST_REMOTE  false 
DISABLE_MOBILE_CACHING_IOS  false 
ENABLE_EXPORT_IMPORT_JOB  false 
COULD_DEL_DISCUSSION  true
REMOVE_STORY_URL_FROM_APPENDIX  false 
TRACE_LEVEL  4
CUSTOMIZE_COMMUNITY_URL  
X509_ISSUER_NAME CN=SSO_CA, O=SAP-AG, C=DE
GEO_LIVE_SYNONYM_SUPPORT false
ALLOW_PUBLICATION_BURSTING false
ALLOW_NON_SAC true
MOBILE_DEFAULT_TAB false
TENANT_SHOW_CURRENCY_AS  
MOBILE_REMOTE_TOKEN HEADER_KEY_1=<<token>>
TENANT_SCALE_FORMAT  
CHART_PROGRESSIVE_RENDERING false
ALLOW_ACN_COPY_CONTENT false
ALLOW_ACN_PACKAGE_SHARING_OEM false

Embedded Role Definitions

PROFILE:sap.epm:Embedded_BI_Admin

PROFILE:sap.epm:Embedded_BI_Content_Admin

PROFILE:sap.epm:Embedded_BI_Content_Editor

PROFILE:sap.epm:Embedded_BI_Content_Viewer

PROFILE:sap.epm:Embedded_BI_User