When an OSLC Link is created, the icon and title of the remote artifact are displayed for all links and remote applications. Out of the box, and for most remote applications, the priority and status of the remote artifact (if any) are also displayed ^[1]. When available, these properties are displayed, by default, as framed-colored text. This default style can be customized to change the color or to rather use an icon instead. Different colors/icons can be configured depending on the priority/status value so they can be easily identified by users. What's more, new properties can be set up to be displayed along (or instead of) the priority/status. The following sections explain how to make all of these settings that together make up the appearance of the OSLC link.

Before starting, it's worth mentioning that each remote property intended to be displayed in the OSLC Link is known as a Link Attribute. Each Link Attribute can be set up to display a different style for each possible value it can have with either a color or an icon. These different styles are known as Link Decorators. In other words, if we wanted to use one color/icon for the priority when it is High, and a different color/icon when it is Low, two Link Decorators must be configured in the Priority Link Attribute. If no Link Decorator is configured for the current value of the remote property, a default color will be used.
Last but not least, remote properties are not mapped automatically to the Link Attribute name; different remote applications may have the same (semantical) property with different names, e.g: status vs state. Because of this, each Link Attribute can be mapped with many Remote OSLC Properties. In the latter example, the Status Link Attribute may be mapped with the status and state Remote OSLC Properties to ensure compatibility with the remote applications using the former or latter property names.

Setting up a Link Decorator

Since the most frequent configuration is to set up a Link Decorator on an existing Link Attribute, let's assume a new style (color/icon) is required for an existing attribute (Priority or Status). Once the configuration page is open:

1. Locate and hover the attribute to modify in the table.
2. Click in the edit icon on the Actions column.
3. In the Update Link Attribute dialog, locate the Link Decorators section and click the Add button.
4. In the Update Link Decorator dialog, type the value of the remote property to style in the OSLC Property Value field. This field is not case sensitive.
5. Pick up the display style by clicking in the corresponding radio button of the Display with field.

If the chosen style was Tag

6. Expand the Color field to pick up of the predefined available colors. If predefined colors are not suitable for the property value, click the button next to the color combo to pick up a custom color.
7. Optionally, if the actual value of the OSLC property is not suitable for rendering, type a more convenient one in the Label field.
8. Click in the Update button.

If the chosen style was Icon

6. Type the (accessible) URL of the image/icon to display ^[2]. ${icon-button}
7. Optionally, if the actual value of the OSLC property is not suitable, as the alternate text to display if the chosen image happens to be unavailable, type a more convenient one in the Label field.
8. Click in the Update button.

If everything goes fine, the Update Link Decorator dialog is closed and the new Link Decorator will be displayed in the Link Decorators table. Repeat the steps 3, 4, 5, 6, 7 and 8 if more decorators were needed. If a change is required on an existing decorator, click the corresponding edit icon in the Actions column of the Link Decorators table. To remove an existing decorator, just click in the corresponding trash icon of the same table.

9. Click in the Update button (of the Update Link Attribute dialog).
10. Click in the Save button at the top-right corner of the main page for changes to take effect.

Do never forget to save any change made by clicking on the Save button at the top-right corner of the main page, otherwise, all configuration done may be lost but don't worry, a warning will prevent you from accidentally leaving the page without saving it first.

Setting up a Remote OSLC Property

As mentioned previously, a remote property is not matched automatically with a Link Attribute name. For doing this matching, each Link Attribute can be associated with several Remote OSLC Properties. If at some point, one remote property uses a name other than the standard (e.g. state vs status) the new (unaligned) property should be added to the Remote OSLC Properties as follows:

1. Locate and hover the attribute to modify in the table.
2. Click in the edit icon on the Actions column.
3. In the Update Link Attribute dialog, locate the Remote OSLC Properties section and type the new property name in the New Property field.
4. Click in the Add button next to the New Property field.
5. Click in the Update button (of the Update Link Attribute dialog).
6. Click in the Save button at the top-right corner of the main page for changes to take effect.

Unlike Link Decorators, Remote OSLC Properties are no visible from the main page, but if everything went OK, the remote property will be accessible and displayed for the Link Attribute when available. There is no way no change a Remote OSLC Property, if a change is required, the previous property must be removed and the new one must be created. To remove a Remote OSLC Property, click the trash icon, in the last column of the Remote OSLC Properties section, once located and hovered.

Setting up a Link Attribute

Now that is known how to set up a Link Decorator and a Remote OSLC Property, it is time to know how to set up a whole Link Attribute. As mentioned before, priority and status attributes are set up out-of-the-box. If, however, a new attribute is required, do the following:

1. Hover the Add Attribute button and click New Custom Attribute.
2. Type a name for the attribute in the Name field. This can be any logical name you want and do not require to match any remote property name as explained before, although in most cases they do.
3. Add a Link Decorator for each known value of the remote property (or properties).
4. Add a Remote OSLC Property for each remote property the attribute is associated with.
5. Optionally, add notes for the attribute in the Notes field.
6. Click in the Create button.
7. Click in the Save button at the top-right corner of the main page for changes to take effect.

If everything went OK, the new attribute will be listed in the main page's table at the bottom. It's worth mentioning that the attributes' order in this table is also the order they will have when rendered in each OSLC Link. If a different order is required, simply drag the attribute to the new position and drop it but do NOT forget to click the Save button at the top-right corner.

It's also worth mentioning that adding a Link Decorator in step 3 is actually not required, a (tag) default style will be provided for unmapped values but what is really important is to set up the Remote OSLC Property in step 4. Ideally, this should be the URI property definition of the mapped OSLC property, but since this can be hard to know or discover, simple property names (not case-sensitive) are also accepted. Having said this, if the URI property definition is not known, what is recommended to type at step 4 is the same name as the Link Attribute. This will work for most cases because most remote applications use straight names for their artifact properties, this means that if the remote artifact has a property called Creator, it's very likely that the property definition URI contains (or can be easily driven to) the string creator. As it can be guessed, this straight name won't work for a remote application if it decided to go on its own and assigned a slightly or very different property name (e.g. publisher, owner, or property456123). For such remote application, the right property name should be added to the Remote OSLC Properties table. Fortunately, there's no need to know or investigate the actual name or a remote property...

Picking up a Link Attribute

If a remote application artifact is available (to drag and drop) and the remote application is already friended with ${local-app}, there's a better/recommended way to add a Link Attribute that ensures the right Remote OSLC Property name will be used and allows to preview how an OSLC Link will actually look when rendered.

1. Drag the remote artifact and drop it in the dropping area below the Link Attributes table.
2. Complete the remote authentication/authorization process if required.
3. Hover the Add Attribute button.
4. Look for the required remote property and click it.
5. Optionally, add Link Decorators if required.
6. Click in the Create button.
7. Click in the Save button at the top-right corner of the main page for changes to take effect.

By using this procedure, all information that can be gathered from the dropped artifact will be used to prefill the Create Link Attribute dialog. This includes the Name field, the Remote OSLC property and the Link Decorators if the remote property has known values.

It's worth mentioning that multiple artifacts (from different remote applications) can be dropped in the dropping area; their properties will be merged in the Add Attribute button list and they can be previewed below the dropping area. If a new Link Attribute needs to be added from scratch, look at the end of the list for the New Custom Attribute option.

Finally, to remove a Link Attribute, click the trash icon in the corresponding Actions column and click the Save button at the top-right corner. Last but not least, to disable all configured Link Attributes (without removing any configuration), uncheck the Enable Link Appearance check box, above the Link Attributes table, and click the Save button.

^[1] Depending on the available space, they can be displayed to the right of the title or when hovering over the three dots icon. ^[2] A Base64 URL format (e.g: data:image/png;base64,...) is also supported here.