(v1) .Service Hosts v2.1.4.7

Service Hosts

The items on the Service Hosts grid populate the drop-down lists of Service Hosts that occur throughout the application. Service Hosts define specific types of services that have special permissions associated with them. An example would be: adding Cisco VoIP service to part of your organization. By defining Cisco VoIP as a Service Host you can then specify the Equipment (and subsequent Service Locations) tied to this Service Host. This enables you to view your organization by Service Hosts as well as eliminate errors by trying to add, for example, TDM voice services where only VoIP services exist and vice versa. By adding items to the grid, Admin Users can add to these lists; by editing existing items, Admin Users can change the contents of these lists; and by deleting items from the grid, Admin Users can reduce these lists.

In any case, the items on the Service Hosts grid represent the hosts that provide phone or other services for the User's organization or its customers.

Adding a Service Host

Navigate to the Service Hosts grid (see image above) by opening the 'Admin' tab and clicking on the node labeled 'System Tables', then the node labeled 'Service Hosts'.

To add a new service host to the grid, click the 'Add' button located immediately above the grid.

In the Service Host data entry form (see image above), the user is prompted to define two required fields: 'Name', and 'Host Type'.

Users can also define a default 'NPA' and 'NXX' to be used during call file processing.

Using the tabs displayed in the graphic above, Admin Users can also add Equipment to the Service Host and add Vendors associated with the selected Service Host.

In the middle section of the form, labeled 'Access Data', Admin Users specify how the system can access this Service Host. These settings are used by the Communication/Switch Modules to connect to the host. The Admin user can set access data by 'IP Address', 'Network Port', 'Username', 'New Password', 'WSDL URI', and 'Version' (see figure below).

Saving the New Service Host

Once all Required fields have been satisfied, click the 'Save New' button located at the bottom of the Service Host data entry form. The new Service Host will appear as an item on the original Service Hosts grid and will be available as a selection whenever a 'Service Host' field is encountered throughout the application.

Editing Existing Service Hosts

Admin Users can edit existing Service Hosts by double-clicking on any item on the Service Hosts grid or by selecting an item and clicking the 'Edit Selected' button located immediately above the grid.

This opens the item's Service Host data entry form, at which point the User can define the item's inputs by following the protocol established earlier in this section. Once all Required fields have been satisfied, click the 'Save' button at the bottom of the form.

Admin Users can delete existing Service Hosts by selecting the appropriate item on the Service Hosts grid and clicking the 'Delete Selected' button located immediately above the grid. The deleted Service Host will no longer appear as an option when users encounter a 'Service Host' data field throughout the application.

Exchanging Data With External Data Stores

Service Hosts can be set up to take advantage of remote data resources via Internet-based APIs. This section will explain how to set up API Service Hosts and utilize them in PCR-360.

Set Up An API Service Host

Go to Admin > System Tables > Service Hosts
Open a new Service Host, and select "REST API" on the Host Type list. The form will update, changing some of the inputs available. The image above shows a sample of the data needed for the new Host.
If the API you're using requires specific HTTP headers, you can use the "Data Encoding" list to select some pre-set headers. You can customize them in the "Request Headers" box. Enter one complete header per line. If you modify the presets, they won't be changed if you select a different "Data Encoding" item. Clear the text box if you want to switch Encoding types to use different preset headers.
Enter the URL to the API that will process your data. The "*https://*" is optional, but our Service Hosts will only send requests over an encrypted connection. APIs that don't support encrypted connections are not supported and strongly discouraged.
To make the Host reusable, use only as much of the API URL as is necessary to establish the connection. For example, many APIs use path segments to indicate how a request should be routed:
- *https://some-other-host.com/api*/customers/1234?*first_name=Jeff*&*last_name=Smith*
  could indicate the customers table, ID # 1234 should update first_name and last_name to the provided values.
- *https://some-other-host.com/api*/order/add
  could mean that an Order needs to be generated. Perhaps this API requires a JSON data object instead of a query string that would look like:
```
{
  "45-abc-67": 1000,
  "~staples":  400,
  "SD_NUMBER": [the Service Desk Number from PCR-360]
}
```
  This may indicate 1,000 of part # 45-abc-67 and 400 of something that looks like "staples", and the ServiceDesk SD Number is needed.
- Notice the only common part of the above examples is the URL entered in the sample image. Everything after "api/" changes depending on what kind of request you're making. Provide the minimum part of the URL you need. The part of the URL that changes will be set in the Escalation Sequences.
If your connection requires authentication, provide the Username and Password. The password will be securely encrypted in the database. Some APIs use a Key string that acts as authentication so you don't need a User/Pass pair. You may need to provide the key as a parameter in the Escalation Sequence, or include it in the Host URL input above. Address specific requirements with the API owner.
Some APIs may also require usage of a configuration file, version, or specific network port to establish connection and/or exchange data. Fill these in as needed.
When all information is complete, Save the Service Host. Note that you cannot change the "Host Type" of existing Service Hosts anymore. This is to avoid retaining or adding invalid data, or removing necessary data, for a given Host Type.

Setting Up Escalations To Utilize The Service Host

We recommend reading the comprehensive coverage of Escalations to understand how they interact within PCR-360, how they are controlled by Events generated by user activity, etc.

To actually exchange data with a remote host, PCR-360 uses its Events system. You can build Escalations that use the Service Host you set up, and when particular actions are taken on 360 data, the Escalation will begin executing, with access to the data you acted on. We have also added support for User Defined fields to be used as Criteria checks, and as Hash Variables in your Escalation's output.

This is a sample Escalation that will use the Service Host set up previously. It will execute using the "New Estimate Created" Event. We'll add a single Sequence and a single Criteria that must match for the Escalation to execute at all.

Go to Admin > Escalations / Notifications > Escalations
Open a new Escalation. You are now required to select a Start Event before adding Sequences. This is to help the Sequence form know what data variables it can use. Select "New Estimate Created" as the Start Event.
Open a new Sequence on the Sequence tab. Set the Sequence # "10", and Time To Wait "0m".
Select "Service Host REST Escalation" from the Type list.
When the form updates, choose the Service Host you want to use ("Sample REST Host" in the example above).
Set the "Host API Path". This will be the part of the URL that differs from one command to another.
1. If the API uses a query string (as described above), do not include it in the Host API Path.
2. If there is no additional path to the API URL, enter "/" as the API Path value.
In the User Defined Table field, you'll add the data parameters you need to submit to the API. This is a map of field names the API expects with values from PCR-360.
Compare this sample to the "Add Order" command from our Service Host example:

Note how the keys and values are set. Users can also use items from the "Event Variables" list to append variable placeholders to the Value you'll send. These variables (formatted as ##VARIABLE_NAME##) will be replaced with the actual value from the Event when the Sequence is executed. The selected item from the list will always be appended to the END of the value string, but you can cut/paste them to other positions in the value as needed.
Regardless if the API uses a JSON string, XML, or a query string, the keys and values are set up here. We currently only support one instance of a key paired to one value. "API Variable" names must be unique, values may repeat. This may be enhanced in later versions.
Note that we've added UDF support to the list of Event Variables you can add to the API Value. When selecting one, there will be a variable name like ##UDF_12345## instead of the label. This ensures the unique UDF ID is used for looking up the correct value to replace the variable with. Should we use a label, and the label changes or contains errant characters, the variable substitution would fail.
Save the Sequence and close the Sequence form. To use this Escalation to perform other tasks, including other Calls to the same or other APIs, set up separate Sequences for those actions.
Click the Criteria tab and open a new Criteria. This operates the same as previous versions. However, you'll notice we've added UDFs that apply to the data object the Start Event is generated from into the list of data Criteria you can check before the Escalation begins its work. There are also additional Comparison types to choose from for better refinement of acceptable data conditions.
Save a Criteria if desired.
Finally, save the new Escalation.

With this sample, when a new Estimate is created in Service Desk, this Escalation will check any Criteria you set in place. If ALL of the criteria pass, the Sequence(s) will execute, sending data to the API you set up in Service Hosts.

Viewing Results

Go to Admin > Escalations / Notifications > Logs > Esc. Sequence Log

You can review the results of all Escalation Sequences here. Double-click a Log item to open it. You'll see the result data laid out as a JSON object with various information about the Sequence execution. For an API Sequence, you'll see "curlResponse", "curlInfo", and "curlError" message keys. These can help you identify problems in your setup of the Service Host or Escalations, or indicate successful execution of sending data to the API. Currently, no processing is done to the response data sent back from the API. It is simply logged here for reference. This may be enhanced in later versions.