Tool Data Sheet

Product Specifics / SAP BTP Services

There are 2 kinds of data sheet topics used to transport common content about the service or tool from the DITA CMS to SLM (Service Lifecycle Management):

For each technical asset of the tool (of your service) in the Discovery Center, the same rules apply as for the service data sheet.

Usually, there is one data sheet per tool. However, if your tool is in different environments, for example, the Neo environment and the Cloud Foundry environment, and if is more than one documentation link is needed, then you need to sync with your PO. You can only add one documentation link per technical asset. So, it might be necessary to create a second technical asset for the tool. If you have a second technical asset, you also need to create 2 datasheets.

In short, this is what you do per technical asset:

The details are described in the sections below. See also, Tools_Data_Sheets.pptx.

Data Sheet Topic Use

The content of the data sheet topic is reused in the service catalog of the SAP Discovery Center.

The text fragments are retrieved from the Help Portal using an API and transferred to the tool (SLM = Service Lifecycle Management), which serves as the backend repository for the service catalog of the SAP Discovery Center.

  1. Container Setup
  2. Create the Data Sheet and Add Content
  3. Add Data Sheet to Buildable Map
  4. Sync Content from Data Sheet on UACP to SLM
  5. Update existing content in SLM
  6. Update the Discovery Center
  7. Remove a Tool from the Discovery Center

Container Setup

If your documentation is inside the ODS_NEO container, you can use that container for your data sheet as well. If you use a separate container for your service, you create the data sheet there.

Then include the to-be-published (maybe SHIP) version of this container as child to the CP_TOP (loioe822305a6b524b71964d5d2a6f465e40) container.

If you run your service-specific container in a "classical" mode and clone it for every new release, make sure that you always update the dependency tree of container CP_TOP with the newest version of your container.

If you want to use a service-specific container for your service but have not yet created it, you need to create it and then run it (preferably) in a push-to-ship mode.

See also: Initial Technical Setup

warning
After you have inserted your service-specific container into the dependency tree of the CP_TOP container, please check if the new dependency tree is still valid.For more information, see: https://help.sap.com/viewer/DRAFT/bba968de69fc4814b97a0da987913be1/1/en-US/7cef1754899a4070810fecd580a969db.html

Create a Data Sheet and Add Content

  1. A template for a data sheet topic is provided in the DITA CMS:
    REFCONT: TEMPLATE Data sheet for TOOL NAME (loio7f6207973ab34cf5bcedf7e116da6ab7)
  2. As a UA developer, use Copy with new loio to create your own data sheet topic in your service-specific container.
  3. You will find the newly created data sheet topic in the "Recent Operations" section of the "Documents" in the DITA CMS.
    Rename it according to the naming convention: "REFCONT: Data sheet for <tool name>"
    (Make sure to remove "TEMPLATE" from the title.)
  4. Together with the product/service owner, agree on the content and enter it into the data sheet topic.
  5. Release the data sheet topic.
  6. If you work in a push-to-ship container setup, push the data sheet topic to the SHIP version of your product container.
    (With that, the data sheet topic is automatically set to "Authoring:done" in the SHIP version.)
    If you work in a "classical" container setup, please set the status of your data sheet topic at least to "Authoring:validation" as data sheet topics will be translated in the context of the centrally provided buildable map.
information
How to deal with existing content in a service guide or in the SLM tool?
The data sheet topic is ultimately the single source of truth for the SLM tool.
Therefore it is important that you copy all information that might currently be in the SLM tool to the data sheet topic, delete the existing content in SLM, and sync it again from the data sheet topic to the SLM tool.

Descriptive Content in Data Sheet Topics for Tools

Follow the instructions in the data sheet topic form when entering text for the following items:

While the DITA CMS allows you to go over the maximum character restrictions listed below, in SLM the Sync with the DITA CMS will fail.

warning

Important Restrictions

Please be aware that the Long Name field is mandatory. Without it, publication to the Discovery Center fails.

Make sure to observe the following length restrictions:

  1. Short Description: < 80 characters
  2. Long Description: < 500 characters

Enter the link to the tool documentation. See top of the page about creating a second technical asset, if you need to set more than one link.

Tools Icon

It's always the same and therefore added when the technical asset is created.

Update the Data Sheet

Depending on the container strategy of your service-specific container, you have to consider the following after you have updated the data sheet topic:

Add the Tool Data Sheet to the Buildable Map

Insert your tools data sheet topic into the buildable map and to the topic.

  1. Lock the CP_DATA_SHEETS (loio3acabdabe0c74593b069d413434b5471) buildable map, which is located in the CP_TOP container.
  2. Drag and drop the newly created data sheet topic from the list of "Recent Operations" into the CP_DATA_SHEETS buildable map.
  3. Right-click your topic and choose "Classify Topics ..." from the context menu
  4. On the "Classification Maps" popup, expand the structure under the "CP_DATA_SHEETS_CLASSIFICATION" entry node.
  5. Select (check) your asset from the list.
    The list is alphabetically ordered and uses the technical name of the asset as maintained in SLM.
  6. Close the popup.
  7. Release the CP_DATA_SHEETS buildable map.
information

If you don't find a proper asset in the list for assignment, it might be due to one of the following reasons:

  • Your tool is in beta/free of charge (see: My service is in beta/free of charge. Do I need to create a data sheet topic?)
  • The commercialization onboarding process for your tool has not been started and an asset has therefore not been created in SLM.The service's product owner should know the status. (See the Technical Cookbook for Pay-Per-Use Service page under 4. Integrate with SAP BTP Products Catalog (SLM).)
  • Assets are not replicated into the DITA CMS immediately. Please inform Herbst, Astrid. Technically speaking, the technical names of assets in SLM and their internally used asset IDs are replicated into a classification map in the DITA CMS regularly. When you assign your topic to an asset from the classification map, the SLM tool can find your topic using its asset ID.

The buildable map with all data sheet topics is build and uploaded to help portal every working day morning: https://help.sap.com/viewer/DRAFT/01cd1c17c9304dc0ba6bc8650bdf3386/1/en-US/

Sync Content from the Data Sheet Topic to SLM

The service owner who drives the commercialization process for the service in SLM will ask the UA to create the data sheet topic.

Once the data sheet topic in the CP_DATA_SHEETS map is republished to Production on the Help Portal, you can access SLM and import the data sheet content. To do so, you must request the SLM Venezia Prod UA profile, using CAM (https://wiki.wdf.sap.corp/wiki/x/yb5skw). It’s a self-service.

  1. Open SML.
  2. Choose Technical Asset.
  3. Search for your technical asset and open it.
  4. Choose Edit.
  5. Choose Sync with DITA CMS.
  6. Choose Start Sync.
  7. Check all entries for correctness.
  8. Choose Save.

In urgent cases, you can maintain the technical asset directly in SLM. Please be aware that these changes will be overwritten with content from the data sheet topic after the next sync.

For more information, see:

Update Existing Content in SLM

You might face the situation where there is already content maintained for your tool in SLM that has not been synced from a data sheet topic.

  1. Review the available content (short description, long description, links) carefully. Make sure that all information that is still relevant and not outdated, is also contained in the data sheet topic.
  2. Delete the available content in SLM.
  3. Sync content again with the DITA CMS (as described above).

Update the Discovery Center

Notify Barry, Shay (in Jira or by mail) that the technical asset in SLM has been updated and that it needs to be reproduced to the Discovery Center.

You can add content for new tools whenever you want – it won't appear on the productive Discovery Center before the official price list update in which the tool becomes available.

Free materials can be released once you/service owners confirm it is ready from your perspective, seeing as this is content only.

For already live tools, any content you update from Tuesday noon to the next Tuesday noon, appears in the Tuesday noon update.

Remove a Tool from Discovery Center

Commercial tools have to go through a formal deprecation notice period.

Non-commercial tools can be removed immediately by Barry, Shay.