Configuration Items in External Interface

Extend Class Definition

The definition of a configuration item class has to be altered to make it able to be displayed in the external interface.

By default, the CustomerID field is configured in the system configuration to store the customer ID information in the configuration item definition.

You can use more than one CustomerID per configuration item, to make one configuration item accessible by more than just one customer. To do so, repeat the following steps for the maximum amount of customers one configuration item may grant access to (for example: PartnerA, PartnerB, PartnerC, etc.).

If your class definition does not contain the CustomerID attribute, then you have to add it manually.

To add the fields for configuration items:

1. Go to the Configuration Items screen.

2. Select a configuration item class and click on the Change class definition button.

3. Add the new fields to the class definition. The input type could be either Text or CustomerCompany.

   Text Field

   Text based field gives the flexibility to use any string as value to match the CustomerID for one or more customers. The value must be entered manually by editing each configuration item, but it needs to be done carefully, because any mismatch will prevent the configuration item to be displayed in the external interface.

   - Key: CustomerID
     Name: Customer Company
     Searchable: 1
     Input:
       Type: Text
       Size: 50
       MaxLength: 100
   

   CustomerCompany Field

   A customer company field needs to have correctly configured customer companies in the system, as it will be presented as a drop-down list in the configuration item add and edit screens. The source of the drop-down will be the list of companies. CustomerID field in all customer users must point to the correct customer ID in customer companies administration.

   - Key: CustomerID
     Name: Customer Company
     Searchable: 1
     Input:
       Type: CustomerCompany
   

4. Save the new definition.

5. Edit a configuration item from the modified class. Find the Customer Company field (or another field you have added) and fill it with the customer ID of an existing customer.

6. Login to the external interface with any customer user that has the customer ID described above.

7. Add the endpoint to external interface (see below).

8. Go to Company Configuration Items. The edited configuration item must be listed.

Define Strictness of Customer ID Restriction

The setting ITSMConfigItem::CustomerCIPermissionByLink is set to 0 by default, so configuration items are only accessible in the external interface if the company (customer ID) of the customer user matches the value of a configured field. If this behavior is more strict than desired or not all configuration items can/should be configured in such a way, the configuration can be changed to consider links between configuration items (permission inheritance by links). When linking configuration items to new tickets in the external interface and in the agent interface (if enabled), only direct permission is considered though (i. e. CustomerID field in configuration item matches).

For example:

• There are multiple computer configuration items assigned to the customer company. All computer configuration items are linked to at least one network configuration item (switches). These devices do not belong to the customer and are therefore not visible. Also the network configuration items are linked to other network configuration items (router).

• By default, only the companies computers are visible under Company Configuration Items, are shown in linked tickets and (depending on the configuration) can be viewed in detail and used for new tickets.

• If the setting ITSMConfigItem::CustomerCIPermissionByLink is set to 1, all switches connected to a computer will be visible under Company Configuration Items, are shown in linked tickets and can be viewed in detail, but not used for to be linked to new tickets.

• If the setting ITSMConfigItem::CustomerCIPermissionByLink is set to 2, the routers will be included as well.

Hide Configuration Item Fields in External Interface

It could be possible that configuration items has fields that customer does not need to view, or that contains sensitive information that customers must not know. For these cases an administrator can restrict a field by placing a simple new attribute NotForCustomer to the field definition on a particular class.

To hide a field in external interface:

1. Go to the Configuration Items screen.

2. Select a configuration item class and click on the Change class definition button.

3. Add the attribute NotForCustomer: 1 to the field definition.

   For example:

   - Key: Vendor
     Name: Vendor
     Searchable: 1
     Input:
       Type: Text
       Size: 50
       MaxLength: 50
     NotForCustomer: 1
   

4. Edit the configuration items of this class in order to create a new version, so the new version will take the new definition.

To avoid the need to create new versions for configuration items if the definition of a class is updated to hide a field from external interface, it will be applied to all configuration items of that class. On the other hand, if the class definition is updated to show a field that was previously hidden and the configuration item was already updated to the class definition where the field was hidden, the field will not be shown until the configuration item is updated to last class definition where the field is set to be shown again.

The intention of this behavior is to enforce the privacy of the data that should not be displayed in the external interface.

Restriction for Linking

This feature restricts the link interface for the agent when linking a ticket with a configuration item. Only configuration items and the tickets which belong to the same company of the customer user can be selected. The feature can be disabled in the system configuration via the setting ITSMConfigItem::RestrictAgentLinking.

Postmaster Filter

There is a postmaster filter added to search incoming emails for a configuration item identifier (usually the configuration item number) and links all found configuration items with the new ticket that was created from this email. The email body and the subject are searched, all found configuration item numbers will be linked with the ticket. This feature is deactivated by default and needs to be enabled in the system configuration via the setting PostMaster::PostFilterModule###100-ITSMConfigItemLink.

Link Configuration Item With Ticket

In the New Ticket screen the customer user can search and select the configuration items that are assigned to his company. When the ticket is created, the selected configuration items will be automatically linked to the new ticket.

To link a configuration item to a new ticket:

1. Create a new ticket in the external interface.

2. Fill in the required fields.

3. Click on the Add affected configuration items button at the end of the ticket form. A new set of fields will appear below.

4. In the new section fill any search criteria for class, name or number.

   • Class drop-down list only shows classes that are already prepared and contain configuration items assigned to a CustomerID.

   • Name field matches any configuration item which name starts with the content of the field. For example, if ca is typed in the field, it will match cat, car, card, etc.

   • ConfigItem# field matches any configuration item which number starts with the content of the field. For example, if 12 is typed in the field, it will match 123, 1211, 1298, etc.

   Note

   These search fields will only reduce the search results in order to have smaller lists to be able to select faster. Leaving them in blank will bring the full list of configuration items assigned to the company of the current customer user.

5. Select the configuration items from the list.

6. Click on the Create Ticket button.

Company Configuration Items

The Company Configuration Items screen shows a list of all configuration items that belong to the same company as the customer user. Belonging to the same company means, that the configuration items must have a CustomerID field that has the same value as the customer user. In the external ticket detail view all linked configuration items that belong to the company of the customer user are shown as well.

If desired, the required association of configuration items to the company of the customer user can be decreased by setting a maximum level to check linked configuration items. If this feature is enabled, configuration items are also accessible to customer users if they do not belong to the company directly, but a linked configuration item is (up to the configured number of links away).

The configuration item details can be access from the configuration items list. This details screen shows the last version of the configuration item, links to other configuration items (if they belong to the same company).

If multiple classes of configuration items are available in the external interface, an All filter is displayed to see all classes. The Class column is always visible, when the filter All is selected.

Clicking on a configuration item will show the detail view.