Creating custom artifact elements

View authors can use custom artifact elements to build views. Custom artifact elements gather artifacts of a specific type based on a SPARQL query, and are used to show artifacts in view containers. In the editor you define or modify the SPARQL query, parameters, and linking relationships with other artifacts.

Before you begin

  • By default, only administrators create, modify, or delete custom artifact elements. For permission requests, contact your administrator.
  • The product comes with a set of predefined custom artifact elements that view authors can use when they build a view. You can modify the predefined custom artifact elements for your project. If you want to learn how to create custom artifact elements, use the predefined ones as examples.

    Go to Views > Browse Custom Artifact Elements to work with the predefined custom artifact elements that are organized in folders by engineering discipline. In the view editor, the custom artifact elements are in the palette. If the custom artifact elements are missing, ask your administrator to deploy the content packages that are available on the application administration Contents page.

About this task

When you create a custom artifact element, it becomes available on the palette in the view editor. View authors can use the new custom artifact element when they build views.

The new custom artifact element is also in the list at Views > Browse Custom Artifact Elements.


  1. Create a folder for the new custom artifact element.

    In the main menu, go to Views > Browse Custom Artifact Elements, and click Create Folder in the upper right corner. Name your folder My custom artifact elements, and click Create.

    Tip: The Create button becomes available if you click outside the name field after you enter the folder name.
  2. Click Create custom artifact element.

    The editor opens. Your custom artifact element is created after you configure the name, ID, template, and SPARQL query, and after you click Create.

  3. Identify your custom artifact element.
    1. Name your custom artifact element My Work Item.
    2. Enter the ID my_work_item.
  4. Click the pencil icon near Template, and select an artifact type that is equivalent to the custom artifact element that you are editing.
    For example select Artifact Types > Change and Configuration Management > Work Item.
    Note: Even if you select a different template, the SPARQL query sample does not change.
  5. Review the sample in the SPARQL query field.

    The comments in the sample help you become familiar with SPARQL queries.

  6. Review the information in the Parameters section.

    Note the parameters artifact, limit, and multipleProjectAreas. These parameters are defined in the SPARQL query. When view authors use the custom artifact element to build a view, they see the parameter type and label on the Set Parameters page.

    Remember that the default project scope of the custom artifact element is the same as the current scope of the view. You can apply a specific scope limited to the Node Container by updating the parameter value of the custom artifact element in the query. You can also apply multiple project areas as the scope for a custom artifact element.

  7. Add enumerations. Complete the following sub-steps to add a new enumeration.
    1. In the Parameters section, click Enumeration Manager.
      Clicking the Enumeration Manager link in the Parameters section
    2. To create a new enumeration, click Add.
      Clicking Add to create a new enumeration
    3. To define the new enumeration, enter data in Name and Values fields.
      Defining an enumeration
    4. In the artifact field, select Enumeration from the first drop-down list.
      Selecting Enumeration
      The new enumeration type Range is now available in the secondary drop-down list of the artifact field.
      The enumeration Range is available in the secondary list of the artifact parameter.
    5. Click Create.
  8. Test the custom artifact element by clicking Preview.
    In the Assign Values to Query Parameters window, you can enter parameter values.
    Selecting a parameter value when you run a query preview.
    1. Click the pencil icon to browse for a specific story.
    2. In the search dialog box type dividend.
    3. To focus only on stories, click Filter by Type. Click the Clear All Filters button, and select only the story type.
    4. In the results window, select story 55: Frequency of dividend transfer.
    5. Click Add.
    6. Click Run Query.
    The selected artifact is shown in the list.
    Artifact in the Query Result window.
  9. Add links to other view elements.

    When view authors use this custom artifact element to create a view, they right-click the element and use the Show Links To wizard to see the links that you configure in the custom artifact element editor.

    1. On the Query Result page, click the link in the resource column.
    2. Click Show Properties.
      Show Properties menu in the query results.

      In the list, you find all the resource description framework (RDF) properties for the resource that you selected. The list helps you create custom artifact elements. Note that the story has a testedBy testCase link.

    3. Copy the URI of the testedBy testCase link.
      Right-click testedBy testCase, and click Copy Link Location.
      Copying the URI of the linking relationship.
      Tip: This is the menu for Firefox. Other browsers have a different menu for the link copying capability.
    4. Modify the SPARQL query to define the related test case.
      1. Click OK to close the Preview Query window.
      2. Paste the copied URI into the SPARQL Query window in the prefix section.

        The URI is The prefix entry should be PREFIX oslc_cm: <>

        Confirm that the prefix is in the sample.

      3. In the SPARQL sample, under ## Fetch Link To relationships, enter this line:
        OPTIONAL { ?resource oslc_cm:testedByTestCase ?testCase }
    5. Launch a preview.
      1. Click Save.
      2. Click Preview.
      3. Click Run Query.
        Note that the linked test case is now included in the results table.
        The link to the test case shows up in the query results list.
    6. In the Links section, click Add.
      An empty row is added to the links table.
    7. In the Variable Name field, select testCase.
    8. Enter the link label Test Case.
    9. In the Linked Artifact field, click the pencil icon and select Artifact Types > Quality Management > Test Case.
  10. Click Create to save your configurations.

    In the Save to window, select the My custom artifact elements folder that you created at the beginning of this procedure.

  11. Test the custom artifact element in a view.
    1. Open a new web browser tab.
    2. Go to IBM Engineering Lifecycle Optimization - Engineering Insights (ENI) at http://server:port/relm/web.
    3. Click your project name on the My Projects tab.
    4. Create a view.
      1. From the main menu, click Views > Create View.
      2. Name the view Custom Artifact Element Test.
      3. Save the empty view in the default My Views folder.
      4. Click Finish.
    5. Add the new custom artifact element to the view.
      1. On the Palette tab, go to the Custom Artifact Elements section. Open the My custom artifact elements folder, and drag the My Work Item element onto the canvas.
        Custom artifact element on the palette.
        Tip: You can also type My work item in the search field to filter the palette item without expanding the list.
      2. In the Set Parameters window, click the pencil icon to browse for an artifact.
      3. In the search dialog box type dividend.
      4. To focus only on stories, click Filter by Type. Click the Clear All Filters button, and select only the story type.
      5. In the results window, select story 55: Frequency of dividend transfer.
      6. Click Add.
      7. Click OK.

      The artifact that you selected is shown in the My Work Item container.

    6. Link the artifact to related test cases.
      Right-click the My Work Item container, and click Show Links To to open the wizard. Use the wizard to add the Test Case container with the test cases that match the selected linking relationship.
      The linked test case is shown in a linked container.
      New custom artifact element that is linked to a related artifact.

What to do next

View authors can use the new custom artifact element when they create views.