Show TOC

Procedure documentationRegistering User Apps in the Dashboard Framework Locate this document in the navigation structure

 

If you have created the user interface of an app, and possibly its configuration app, with Dashboard and Presentation Design (Xcelsius) (there is a detailed example under Tutorial: Creating and Registering Dashboard Apps), you can register it in the dashboard infrastructure. You can then display your app in all relevant dashboards.

Prerequisites

The following steps are prerequisites for registration:

  • You have used Xcelsius to create the user interface of your app and your configuration app (if applicable) (see also Enhancing the Dashboard Framework with User Apps)

  • You have created Flash files for your app from Xcelsius. These Flash files are displayed in the dashboard.

  • You have created an image file that is to represent the app as an icon in the dashboard framework interfaces. This image file has the file type JPG and is displayed at a maximum size of 100 x 100 pixels.

  • You have selected a suitable category for the app. Categories group the apps by topic, and therefore also determine which apps can be added to a dashboard. To obtain an overview of the categories that exist, start the registration tool (see below); the existing apps are displayed there, grouped by the different categories.

  • You have selected a suitable authorization group for the app. You can use these groups to define who is permitted to display and configure which apps. The authorization groups are based on the categories.

Transport App Registration

If you want to transport the app and the associated configuration app in your system landscape (but only then), you need to have created the corresponding transport requests before registering the apps. You need to have created these requests with the user that you use to perform the registration of the app and the configuration app. You need two requests, which you create in your development client, by default:

  • You need to create a Workbench request. Immediately after you create it, this request contains one unclassified task. Classify this task by selecting the task in transaction SE09 and choosing   Request/Task   Change Type  . The Change Task Type screen appears. Select the radio button Development/Correction.

  • Create a Customizing request.

Specify these transport requests in the General Settings field in the Customizing Request for App Type and Workbench Request for Files fields (see below).

The way the system transports the app when you register it, depends on the client settings in your system (you can see the client settings in transaction SCC4):

  • If no changes are allowed to client-specific or repository objects, you cannot create and transport user apps.

  • If the radio button Changes without Autom. Recording, Transport Not Allowed is active in the client-specific object settings, you can create user apps, but the transport request fields are not ready for input. You cannot transport your apps.

  • If the radio button Changes without Autom. Recording is active in the client-specific object settings, you can transport the app. The transport request input fields are ready for input.

  • If the radio button Automatic Change Recording is active in the client-specific object settings, you must specify the transport requests when you register your app.

You must assign your apps to a package. You must have created this package before registering the app.

Note Note

If you have transported an app once, you must transport all its changes. If you have created an app without a transport request (indicated by the text Local App next to the transport request input fields in the first step of the registration wizard), you can transport the app later, by choosing Transport App in the registration tool.

End of the note.

Procedure

You register the app in your SAP Solution Manager system.

  1. If you want to transport the app, log on in English when registering the app.

    Note Note

    When you edit an app, you must do so in the language in which you registered it.

    End of the note.
  2. The registration is performed using a Web Dynpro application called dashboard_apploader. Call a Web Dynpro application as follows:

    1. In the SAP Easy Access menu, call   Favorites   Add Other Objects  .

    2. From the list in the Restrictions screen, choose Web-Dynpro Applications.

    3. On the Web Dynpro Application screen, in the Web Dynpro Application field, enter the name dashboard_apploader.

    4. Enter a description, for example Registration of Apps, and complete the creation of the new entry.

    Now start the registration by double-clicking the entry that you have just created.

  3. Choose Register New App.

  4. If your app could, but need not be, transported, according to your system settings (see Transport App Registration above), you are asked whether to transport the copied app.

  5. On the General Settings screen, enter the following data:

    Input Field During Registration

    Meaning

    Radio button Standard App/Configuration App

    Choose the relevant radio button. If you want to register an app with an associated configuration app, you need to perform the registration in two steps. In this case, register the app itself first (Standard App).

    Technical Name

    Specify a unique technical name for the app. The technical name does not need to begin with Y or Z.

    Note Note

    Note that you can only use the characters 'A' - 'Z', '0' - '9', and '_' for the technical name.

    End of the note.

    Short text

    Enter a descriptive short text for the app. The app is displayed in the dashboard framework interfaces using this short text.

    Description

    Enter a description of the app. If you want to add a new app to a dashboard, the app description is displayed during this process.

    Namespace

    Specify the app`s namespace.

    The namespace classifies your apps technically. You can create a new namespace, with Create Namespace. In a new window, you can enter the technical name and description of the namespace, and the package to which the namespace is to be assigned. If you create a local app, the namespace is assigned to the package $TMP automatically.

    Note Note

    The namespace is saved with the app, at the end of the wizard.

    End of the note.

    Categories

    In the dropdown list box, choose the entry that represents the appropriate topic for the app from the user's point of view; you can specify multiple categories.

    Authorization Group

    Specify the authorization group to which the app is to belong. Roles delivered by SAP contain display authorization for apps with the authorization group Public.

    App Flash File (SWF)

    Specify the app's Flash file. You created this file with Xcelsius (menu path   File   Export   Flash (SWF)  ).

    Icon File (JPG)

    Specify the storage location of an image file that is to represent the app in the relevant interfaces.

    Xcelsius File (XLF)

    Specify the storage location of the Xcelsius file that contains the user interface of the app.

    Note Note

    When you upload the above files to your system during registration, ensure that they are virus-free. You can ensure this by Setting Up a Virus Scan Provider.

    End of the note.

    Customizing Request for App Type

    Workbench Request for Files

    These fields are only ready for input if the prerequisites above have been satisfied. If you want to transport the app, specify the requests here that you created before registering the app.

    Has Configuration App/Has Partner App Flags

    You can use this indicator and the associated dropdown list box to create the connection between the app and the associated configuration app.

    Only select this indicator if the partner app for the app or the configuration app has already been registered in the dashboard framework. Since you normally register the app first and then the configuration app, create this connection only when registering the configuration app, by selecting the Has Partner App indicator, and specifying the associated app in the dropdown list box.

    If there is no configuration app for your app, do not select the indicator.

    Update Existing Instances Flag

    This flag is only displayed when you correct an existing app, not when you first register an app.

    This ensures that the app is updated automatically in all dashboards which use it. If the app is not yet used in dashboards, because it is still in the development or test phase, do not set this flag.

    Now move to the next step of the registration by choosing the Next button.

  6. On the Data Sources of Apps screen, specify the sources of the data that is displayed in the app. These are usually one or more BW queries and configurable texts, which you can usually set in the configuration app:

    • Data from BW Query: If data that you want to display in the app comes from a BW query, select this indicator. In the apps delivered by SAP, this is almost always the case, since the dashboard framework is based on displaying data from Business Warehouse.

    • Data from BAdI: If data that you want to display in the app comes from a BAdI, select this indicator.

    • Data from Dashboard Context: Select this indicator, if you want to register a context app. A context app sets conditions not only for an app (as is the case with a configuration app), but for all apps of a dashboard that have the relevant connections. A context app is therefore always displayed within a dashboard. A typical example of a context app is the app for selecting the date that is displayed in the alert management dashboard.

    • Other Values (Text, Numbers, etc.): If your app has values that should only be defined during registration, or has configurable or translatable texts or values that are set in the configuration app (for example, threshold values), select this indicator.

    • If you are registering a configuration app, the indicator Include Partner App Data Sources is also shown. Ensure that the indicator is selected, so that the data sources of the app are also available to the associated configuration app.

    Note Note

    In the next steps of the registration, you specify the details of your data sources, depending on which of these indicators you have set.

    End of the note.

    As of this step, the left of the screen shows a preview of the user interface of the app, along with the connections that you have defined in Xcelsius for this app. These connections are responsible for data retrieval and data exchange for the app. You need to define the data flow in detail for all of these connections during the registration of the app.

    Note Note

    By selecting the Wait for Changes indicator in the App Connections table, you can have a change in the data for the connection generate an event in the backend that immediately reacts to this change.

    End of the note.

    Now move to the next step of the registration by choosing the Next button.

  7. If, in the step App Data Sources, you set the Data from BW Query flag, you go to the BW Data step. In this step, you specify the relationship between the app and the BW query that provides the data to be displayed.

    The page consists of three different tables:

    • In the first table, you insert a row for each BW query that supplies data for the app to be registered. In the column Technical Name, enter the technical name of the BW query.

      Note Note

      In BW queries, the initial value for characteristics is the number character (#). If this initial value is not to be displayed in the app, select the indicator Suppress '#' for the associated query. If the indicator is selected, the initial value number sign is replaced by a space.

      End of the note.
    • In the table Filter for BW Query, you can set the values for each query for which the query data is to be filtered. You specify the technical details of these filters:

      Column

      Possible Value

      Meaning

      Filter Type

      BW: Info Object

      BW: Variable

      In this column, you specify the type of the object for which you want to filter.

      InfoObject/Variable

      <technical name>

      In this column, you specify the technical name of the InfoObject or variable with which the values of the query are to be filtered.

      Source Type

      Fixed Value

      Context

      Connecting the Configuration App

      In this column you specify where the values for the filter come from:

      • Fixed Value: The filter is to have an unchangeable fixed value/initial value. Depending on whether this is a number or a range, enter the value either only in Source/Value from or in Source/Value from and Value To.

      • Context: The value for the filter comes from a context app (see previous step). Specify the name of the data source for this context in the column Source/Value from. This is the technical name that you specified – if you are registering a context app – in the step Data Provided by Dashboard Context in the column Data Name .

      • Connecting the Configuration App: The filter value is set in a configuration app. Leave the columns Source/Value from and Value to empty.

      Source/Value From

      Value To

      Depending on the settings in the Source Type column (see descriptions for this column), you specify either the default value for a filter value or a data source for a context here.

      Name of the Outgoing Connection

      If you specified for the Source Type the value Configuration App Connection, in this column, specify the outgoing connection of the configuration app, in which the info object is restricted.

    • In the Usage of BW Query Result in App table, you specify how the results of the query are used. There is already a row in the Data Source column, with the entry RESULT. Specify here the app's connection to which the data provided by the query is forwarded.

      You can also specify additional connections here, with which you can usually transfer filter values to the query (in the case of a configuration app), or receive them from the BW query for display in the app. In the App Connection Name column, specify the name of the Xcelsius connection; in the Data Source column, specify the technical name of the info object used as the filter.

    • If you want to preprocess or postprocess your query data using a BAdI, you can specify this in the dropdown list box BAdI for Pre- and Postprocessing. Use the enhancement spot IF_DFWK_BADI_BW_PROCESSING to do this (package   AI_SOLMAN_DASHBOARDS   Embedded Packages   AI_DSH_CORE   Enhancements   Enhancement Spots   IF_DFWK_BADI_BW_PROCESSING   ).

      This enhancement spot contains the following methods:

      • PRE_PROCESS: Use this method to process data before the BW query is called, for example, to influence filters.

      • POST_PROCESS: Use this method to process the data supplied by the BW query.

    • The values of different BW InfoObjects are transferred by the query in a user-dependent format,such as 0TIME or 0CALDAY. If the values of these InfoObjects are only to be displayed in the app, this is not a problem. However, if you want to perform calculations in the Xcelsius user interface based on the transferred values, or want to postprocess query data using a BAdI, this will lead to errors, since you cannot know, when creating the Xcelsius user interface, which user-dependent format will be used to transfer the values from the query.

      To solve this problem, you can specify a list of BW InfoObjects that are to be transferred unformatted by the query (and which are therefore independent of the respective user settings). To call this list, follow the link List of Unformatted Info Objects. To add a BW InfoObject to the list, choose the Add button, specify the technical name of the info object, and choose the OK button.

    Now move to the next step of the registration by choosing the Next button.

  8. If, in the step App Data Sources, you set the Data from BAdI flag, you go to the BAdI Data step. You primarily use this option for data retrieval if it is not possible to supply the data using BW queries - for example, if you are reading your current data directly from the SAP Solution Manager. Use the enhancement spot IF_DFWK_DS_BADI_DATA for the implementation of the BAdI (package   AI_SOLMAN_DASHBOARDS   Embedded Packages   AI_DSH_CORE   Enhancements   Enhancement Spots   IF_DFWK_DS_BADI_DATA   ).

    This enhancement spot contains the following methods:

    • GET_CONTENT: Use this method to use the BAdI as a data source; in this case, in the registration tool, you need to assign each of the possible values of the method parameter I_NAME an Xcelsius connection (Inbound App Connection) with the property Is Write (the Xcelsius connections are displayed in the App Connections subscreen of the registration tool).

    • SET_CONTENT: Use this method to use the app as a data source for the BAdI (for example, in the case of a configuration app); in this case, in the registration tool, you need to assign each of the possible values of the method parameter I_NAME an Xcelsius connection (Outbound App Connection) with the property Is Read.

    Note Note

    The implementation of a BAdI requires advanced programming knowledge that is beyond the scope of this documentation.

    End of the note.

    In the registration tool, you enter your enhancement implementation in the table BAdIs, in the BAdI Filter Value column. You then enter the following data for each implementation:

    • In the Parameters Used in BAdI table, enter the technical name and the values of the parameters that you used in the BAdI implementation.

    • In the table BAdI Results and App Connection Data Flow, specify the connections between the conents names in the BAdI and their app connections. You set the content name in the BAdI implementation as possible values of the method parameter I_NAME.

    Now move to the next step of the registration by choosing the Next button.

  9. If, in the step App Data Sources, you set the Data from Dashboard Context flag, you go to the Dashboard Context Data step. In this step, in the Data Name column, you specify a name for a data source that can then be used by the apps that use this context. For this data source, specify the associated Xcelsius connections, separated by inbound and outgoing Xcelsius connections. This data source can have any name inasmuch as you only define it during registration, that is, it is not specified in the connections or elsewhere in the associated Xcelsius file.

    Now move to the next step of the registration by choosing the Next button.

  10. If, in the Apps Data Sources step, you set the flag Other Values (Text, Numbers, etc.), you go to the Texts, Values, etc. step. In this step, you specify the data sources for other connections of your app, that is, for connections with which the values (such as texts to be displayed) do not come from a BW query, but rather from the associated configuration app, or for texts that are to be translatable. Enter the following data:

    • In the table, enter a Data Group Name for each connection. This can be any name, you define it during registration, so it is not specified in the connections, or elsewhere in the associated Xcelsius file.

    • For each of these data groups, now define whether the associated texts is defined by a configuration app (indicator Is Configurable per App), and whether the text displayed in the user interface is to be translated (indicator Is Translatable).

    • Assign one of the app's connections to the data group; you can see the possible connections in the App Connections subscreen. Depending on whether this is a connection that writes values to the app (Is Write) and/or reads values from the app (Is Read), specify an Inbound App Connection and/or an Outbound App Connection.

    • A cell range is assigned to each connection in the Xcelsius file. The first row of this area is reserved for the technical names. You reproduce this cell range here during the registration, taking the number of rows and columns from the connection in Xcelsius.

      In the first row, enter any technical name for the object (you can use the object's content to program in Xcelsius), ensuring that you do not leave the corresponding cells empty in the registration tool. The other rows contain the default values for the corresponding objects.

    Note Note

    The length of the text objects is restricted to 255 characters.

    End of the note.

    Go to the next step in the registration by choosing the Next button.

  11. To enable navigation to other apps, dashboards or other elements, in your app, specify it in the Navigation step. See Navigation in the Dashboard Framework.

    Go to the next step in the registration by choosing the Next button.

  12. In the App Type Settings step, you can check your settings again. Exit the Wizard by choosing the Finish button.

Result

You have registered an app in the Dashboard Framework. If there is also a configuration app for your app, you also need to register this app.