Business Hours Web Service

This use case illustrates procedures that an administrator can deploy to create and manage business hours definitions to filter views using the npc RESTful web services.
You can create and manage business hours definitions and deploy them to filter views using the
businesshours
web service. Local admin users can enhance reporting by creating sets of business hours definitions. Business hours help product operators prioritize their troubleshooting workload by highlighting events that occur during business-critical time periods.
Use the groups web service to create site groups, and use the business hours web service to manage business hours definitions. If you add business hours first, you can then associate them with site groups during site-group creation.
You can add and delete multiple business hours definitions and assign them to site groups.
In this use case, we describe the steps to take when using a REST client, a generic web services user interface application. The examples in this use case contain URIs that are constructed using the default server port, 8181.
In this article:
Verify the Prerequisites
  • You have connected the REST client that you will use to invoke the PC web services to the PC RESTful web services.
  • You are a local admin user.
Access the businesshours Web Service Documentation
As a local admin user, issue the following call to see the parameters for the
businesshours
web service:
http://
PC_host
:8181/pc/center/webservice/businesshours
As a local admin user, issue the following call to see a list of supported operations:
http://
PC_host
:8181/pc/center/rest/businesshours/documentation
Create Site Groups Using Web Services
Create and configure a site group that is associated with the Default Tenant using the
groups
web service. You can create rules and apply them to site groups so that items are added automatically. The steps to create groups within a custom tenant are slightly different. You can supply the group ID or the group path as parameters.
For more information about how to create site groups, see Groups Web Service.
Manage Time Zone Associations
You can manage associations of time zones with site groups using web services.
Assign a time zone to a site group using the following URL in a PUT operation:
http://
PC_host
:8181/pc/center/webservice/businesshours/assign/timezone/site/siteGroupId
Remove the assignment using the following syntax in a PUT operation:
unassign/timezone/site/siteGroupId
Get a list of time zones that are assigned to site groups using the following syntax:
http://
PC_host
:8181/pc/center/webservice/businesshours/timezonesAssignedToSites
Remove a time zone association by running the same method with the
unassign/timezone
syntax.
Follow these steps:
  1. Using the REST client with a connection to the
    NetOps Portal
    server, enter a URL for the
    NetOps Portal
    RESTful web services API in the REST client. Use the following format:
    http://
    PC_host
    :8181/pc/center/webservice/businesshours/assign/timezone/site/siteGroupId
  2. Select
    PUT
    for
    "HTTP" Method
    .
  3. Provide a valid Username and Password for a user account that has administrator access to
    NetOps Portal
    .
  4. Select
    application/xml
    as the
    'Body Content-type'
    in the Body settings.
  5. Add the following XML within the
    Body text
    section:
    <GroupTree path="/All Groups"> <Group name="East Coast USA" desc="This is a site group" inherit="true" type="site group" location="North America" bHourID="99990" timeZone="EST"/> </GroupTree>
    • bHourID
      The internally assigned identifier of the business hours definition that you created previously.
    • timeZone
      The time zone to associate with this site group.
  6. Run the method.
    If it does not already exist, the USA site group is created under the default All Groups group in the Groups tree. The Eastern Standard timezone (EST) is assigned to this site group.
  7. Repeat the preceding steps until you have associated time zones with all site groups to which you plan to apply business hours.
Create a Business Hours Definition
You can create business hours definitions using the business hours web service and any REST client. For this procedure, you can log in as a global administrator or as a tenant administrator. The global administrator creates the business hours definitions within the Default Tenant, while the tenant administrator creates the definition within that tenant.
The steps to create business hours within a custom tenant are slightly different. You can supply the tenant ID as a parameter.
Business hours definitions comprise a starting hour and an ending hour. The
startHour
and
endHour
parameters in the XML must be the same for all days to avoid an error in any POST or PUT operation.
For systems with multiple tenants, specify the tenant in the URL. To get a list of tenant IDs, perform a GET to the following URL:
http://
PC_host
:8181/pc/center/webservice/tenants/idNames
You can also modify business hours within a custom tenant by performing a PUT operation to the following URL:
/businesshours/tenantId/
tenant Id
/id/
id
where
id
is the ID of the business hours definition.
Follow these steps:
  1. Using the REST client with a connection to the
    NetOps Portal
    server, enter a URL for the
    NetOps Portal
    RESTful web services API in the REST client. Use the following format:
    • Default Tenant:
      http://
      PC_host
      :8181/pc/center/webservice/businesshours/
    • Specific Tenant
      http://
      PC_host
      :8181/pc/center/webservice/businesshours/tenantId/
      tenant_ID
  2. Select
    POST
    for
    "HTTP" Method
    .
  3. Provide a valid Username and Password for a user account that has global administrator or tenant administrator access to
    NetOps Portal
    .
  4. Select
    application/xml
    as the
    'Body Content-type'
    in the Body settings.
  5. Add the following XML within the
    Body text
    section:
    <BusinessHour> <Name>Bakery</Name> <Description>HEB Bakery</Description> <Monday> <HourRange startHour="5" endHour="12"/> </Monday> <Tuesday> <HourRange startHour="5" endHour="12"/> </Tuesday> <Wednesday> <HourRange startHour="5" endHour="12"/> </Wednesday> <Thursday> <HourRange startHour="5" endHour="12"/> </Thursday> <Friday> <HourRange startHour="5" endHour="12"/> </Friday> <Saturday/> </Sunday> </BusinessHour>
    In this example, a business hours definition named Bakery is created. The business hours start at 5 a.m. and end at noon. Saturday and Sunday are excluded.
  6. Run the method.
  7. Repeat the preceding steps until you have created as many business hours definitions as you require.
Manage Business Hours Associations
Apply business hours filter by associating a business hours definition with a site group. The following procedure details how to assign business hours to a site group.
Remove a business hours assignment to a site group using the following syntax in a PUT operation:
unassign/businesshour/site/siteGroupId
Remove a business hours definition association with a site group by running the method with the
unassignbusinesshour
syntax.
Follow these steps:
  1. Using the REST client with a connection to the
    NetOps Portal
    server, enter a URL for the
    NetOps Portal
    RESTful web services API in the REST client. Use the following format:
    http://
    PC_host
    :8181/pc/center/webservice/businesshours/assign/businesshour/
    businessHourId
    /site/siteGroupId
    • businessHourId
      The internally assigned identifier of the business hours definition that you created previously.
  2. Select
    PUT
    for
    "HTTP" Method
    .
  3. Provide a valid Username and Password for a user account that has administrator access to
    NetOps Portal
    .
  4. Select
    application/xml as the
    'Body Content-type'
    in the Body settings.
  5. Add the following XML within the
    Body text
    section:
    <GroupTree path="/All Groups"> <Group name="East Coast USA" desc="This is a site group" inherit="true" type="site group" location="North America" bHourID="99990" timeZone="EST"/> </GroupTree>
  6. Run the method.
    If it does not already exist, the USA site group is created under the default All Groups group in the Groups tree. The business hours definition with ID 99990 is assigned to this site group.
    NetOps Portal
    validates the site group for an associated time zone by performing a verification. If the site group does not have a time zone assignment, an error message appears.
  7. Repeat the preceding steps until you have associated time zones with all site groups to which you plan to apply business hours.
Query the RIB to Return a View with Business Hours Filtering
You can return data for a specific metric by entering queries into a web browser by querying the Report Information Base (RIB). This example presents a
NetOps Portal
RIB query that returns Top Discards data from a data aggregator data source.
Precede the
NetOps Portal
RIB queries with the following URL:
http://
PC_host
:8481/dm/rib/query/
You can append URL parameters to specify property values:
http://
PC_host
:8481/dm/rib/query/ribquery/?property1=value1&property2=value2
The following RIB query returns Top Discards data from a data aggregator data source:
http://<server IP address>:port/dm/rib/query/SELECT .PollItem.ID, .PollItem.DevDisplayName, .Item.DisplayName, .Discards.Sum, .DiscardsIn.Sum, .DiscardsOut.Sum FROM CA.IM.DA.MF.NormalizedPortInfo.IFSTATS WHERE .Group.GroupID = 1039 AND .EndTime(300) > 1366208760 AND .EndTime(300) <= 1366212360 GROUPBY .PollItem.ID, .Item.DisplayName, .PollItem.DevDisplayName ORDERBY .Discards.Sum DESC LIMIT 10
If necessary, you can escape the RIB query and parameters in your web browser, for example:
http://
PC_host
:port/dm/rib/query/SELECT%20.PollItem.ID,%20.PollItem.DevDisplayName,%20.Item.DisplayName,%20.Discards.Sum,%20.DiscardsIn.Sum,%20.DiscardsOut.Sum%20FROM%20CA.IM.DA.MF.NormalizedPortInfo.IFSTATS%20WHERE%20.Group.GroupID%20=%201039%20AND%20.EndTime(300)%20%3E%201366208760%20AND%20.EndTime(300)%20%3C=%201366212360%20GROUPBY%20.PollItem.ID,%20.Item.DisplayName,%20.PollItem.DevDisplayName%20ORDERBY%20.Discards.Sum%20DESC%20LIMIT%2010
Add the following URL parameters to return Top Discards data for a set of business hours in a specific time zone.
NetOps Portal
Administrators configure sets of business hours.
Some queries support only data filtering by time zone and business hours.
  • RIB.TimeZone
    Is the string identifier of the time zone used to filter data results.
  • RIB.BusinessHours
    Is the
    NetOps Portal
    ID of the business hour definition used to filter data results. Include this parameter in the
    propertiesToTranslate
    value to ensure that the ID is translated. IDs that are not translated are submitted unchanged to each applicable data source.
  • propertiesToTranslate
    Is a list of parameter names whose values contain a
    NetOps Portal
    ID to translate to a local data source ID.
Example 1
To return data filtered by time zone, add the time zone parameter (shown in bold text) to the URL. In the following example, the data is filtered to include only data for items in sites configured for the America/New_York time zone:
http://pchost:8481/dm/rib/query/SELECT .PollItem.ID, .PollItem.DevDisplayName, .Item.DisplayName, .Discards.Sum, .DiscardsIn.Sum, .DiscardsOut.Sum FROM CA.IM.DA.MF.NormalizedPortInfo.IFSTATS WHERE .Group.GroupID = 1039 AND .EndTime(300) > 1366208760 AND .EndTime(300) <= 1366212360 GROUPBY .PollItem.ID, .Item.DisplayName, .PollItem.DevDisplayName ORDERBY .Discards.Sum DESC LIMIT 10?RIB.TimeZone=America/New_York
Example 2
To return data filtered by time zone and business hours, add the time zone and business hours parameters (shown in bold text) to the URL. In the following example, the data is filtered to include only data for items in sites configured for the America/New_York time zone and business hours matching the
NetOps Portal
definition for ID 6434:
http://pchost:8481/dm/rib/query/SELECT .PollItem.ID, .PollItem.DevDisplayName, .Item.DisplayName, .Discards.Sum, .DiscardsIn.Sum, .DiscardsOut.Sum FROM CA.IM.DA.MF.NormalizedPortInfo.IFSTATS WHERE .Group.GroupID = 1039 AND .EndTime(300) > 1366208760 AND .EndTime(300) <= 1366212360 GROUPBY .PollItem.ID, .Item.DisplayName, .PollItem.DevDisplayName ORDERBY .Discards.Sum DESC LIMIT 10?RIB.TimeZone=America/New_York&RIB.BusinessHours=6434&propertiesToTranslate=RIB.BusinessHours
Troubleshooting
Errors are returned if valid syntax invokes a definition that is not itself valid. For example, you attempt to create a site group. The syntax includes the
businessHourId
for an invalid business hours definition. In such a case, the HTTP Response XML includes an error message similar to the following text:
<Group bHourID="99990" desc="This is a site group" inherit="true" location="North America" name="East Coast USA" result="Error with validating business hour ID: Business hour definition with an ID of '99990' not found!" timeZone="EST" type="site group"/>
Business hours definitions comprise a starting hour and an ending hour. The
startHour
and
endHour
parameters in the XML must be the same for all of the days that are included in the definition. Otherwise, you see an error in POST or PUT operations.