SubscribeOp

This operation returns an enumeration context, which you can then use with the PullOp operation to get batches of new or updated incidents from the service. The service maintains an event queue of new or updated incidents. If an existing incident changes several times, the service adds the incident to the event queue several times (the service does not consolidate the events).

The value of the EventQueueSize parameter on the management server constrains the size of the event queue. (See Service Configuration.) To prevent the service from deleting events from the queue, you must pull batches of updated incidents at appropriate intervals. Consider using the following procedure to manage a subscription:

1. Use the SubscribeOp operation to get an enumeration context.
2. Immediately after SubscribeOp returns the enumeration context, start a PullOp operation. As soon as the event queue contains events, PullOp returns a batch of incidents.

   If the event queue remains empty for the specified OperationTimeout, PullOp returns a TimedOut fault.

3. Immediately after the PullOp returns incidents or a fault, start another PullOp operation.

   This step ensures that you always have a PullOp running, which should prevent the event queue from becoming too large.

   CAUTION: If you restart the HPOM Incident Web Service, the service releases any enumeration contexts. The service does not maintain an event queue of new or updated incidents until the client subscribes again. This situation can also arise if the management server is part of a cluster and a failover occurs.

Input

SOAP Body

Element wse:Subscribe of type wse:SubscribeType, which contains the following subelements:

• Element wse:Delivery of type wse:DeliveryType. wse:Delivery attribute Mode must have the following value:

  http://schemas.dmtf.org/wbem/wsman/1/wsman/Pull

• Optional element wse:Expires of type wse:ExpirationType.

  Contains either a duration that specifies how long the client requires the subscription, or a date and time at which the subscription should expire. If you omit this subelement, the service uses the value of the SubscriptionExpiration parameter on the management server. If you specify a duration that exceeds the value of the SubscriptionExpirationMaximum parameter, the service uses the value of SubscriptionExpirationMaximum instead. (See Service Configuration.)

• Optional element wse:Filter of type wse:FilterType or wsman:Filter of type wsman:dialectableMixedDataType. For compatibility with different toolkits, the service supports a filter of either type, but you must specify only one of them.

  Filter attribute Dialect must have the following value:

  http://schemas.hp.com/opr/ws/ServiceOperation/IncidentManagement/1/IncidentFilter

  Filter must contain the subelement incFil:IncidentEventingFilter of type incFil:IncidentEventingFilter. IncidentEventingFilter can contain any of the following subelements:

  • Optional element incFil:Severity of type inc:Severity_OpenType
  • Optional element incFil:EmittingNode of type incFil:EmittingNode
  • Optional element incFil:Category of type xs:string
  • Optional element incFil:Application of type xs:string
  • Optional element incFil:Object of type xs:string
  • Optional element incFil:EmittingCI of type incFil:EmittingCI
  • Optional element incFil:CorrelationKey of type xs:string
  • Optional element incFil:Type of type xs:string
  • Optional element incFil:EscalationStatus of type xs:string
  • Optional element incFil:ConditionMatched of type xs:boolean
  • Optional element incFil:ForwardToTroubleTicket of type xs:boolean

    incFil:ForwardToTroubleTicket enables you to filter incidents, depending on whether the corresponding HPOM message is flagged for forwarding to an external trouble ticket system.

  • Optional element incFil:ForwardToNotification of type xs:boolean

    incFil:ForwardToNotification enables you to filter incidents depending on whether the corresponding HPOM message is flagged for forwarding to an external notification system.

  • Optional element incFil:Title of type incFil:KeywordFilter
  • Optional elements incFil:ChangeType of type xs:string

    incFil:ChangeType enables you to filter incidents depending on how they have changed (whether they are new, updated, closed, or reopened). incFil:ChangeType must contain one of the following strings:

    • new
    • modified
    • closed
    • reopened

      For example, if you are interested in new incidents only, you specify a filter with a incFil:ChangeType subelement that contains new. To subscribe to a combination of change types, specify several incFil:ChangeType subelements.

      To subscribe to all change types, you can omit the incFil:ChangeType subelements.

  • Optional element incFil:CustomAttributes of type incFil:CustomAttributes

    The service enumerates all incidents that match the contents of the incFil:IncidentEventingFilter subelements that you specify. For more details on incident attributes, see Incident to Message Mappings.

    If you omit Filter, the service enumerates all incidents that have the status open or work in progress.

SOAP Header

• Element wsa:Action of type wsa:ActionType that contains the following string:

  http://schemas.xmlsoap.org/ws/2004/08/eventing/Subscribe

• Element wsman:ResourceURI of type wsman:AttributableURI

  Contains a string that identifies the resource type. You can use the element wsa:ReferenceParameters/wsman:ResourceURI from an element of type wsa:EndPointReferenceType.

  Alternatively, create a wsman:ResourceURI element that contains the following string:

  http://schemas.hp.com/ism/ServiceOperation/IncidentManagement/1/Incident

• Optional element wsman:OperationTimeout of type wsman:AttributableDuration

  Contains a maximum duration within which you expect the service to respond. On an HPOM for UNIX management server, the service returns a TimedOut fault if it cannot respond in time.

For an example, see Subscribe Request SOAP Envelope Example.

Output

The SOAP body contains an element wse:SubscribeResponse (of anonymous type), which contains the following subelements:

• Element wse:SubscriptionManager of type wsa:EndpointReferenceType.

  Contains the subelement wsa:ReferenceParameters/wse:Identifier of type wse:Identifier, which you use to identify the subscription if you unsubscribe or renew it. (See UnsubscribeOp and RenewOp.)

• Element wse:Expires of type wse:ExpirationType.

  Contains a duration, for which the service maintains the subscription. You can use the RenewOp operation to renew the subscription before it expires. (See RenewOp.)

• Element wsen:EnumerationContext of type wsen:EnumerationContextType.

  Contains a string that identifies the enumeration context. Use EnumerationContext with the PullOp operation to get batches of updated incidents from the service. (See PullOp.)

Fault

If it cannot return the enumeration context, the service returns a fault according to the WS-Management standard.