Invocation Service

The Invocation Service allows ECHO users to request that ECHO invoke an operation on a registered web service implementation enabling the brokering of services. A user specifies the implementation, operation, and parameters to a service, such as Event Notification Service, and ECHO will invoke the requested service.

ECHO tracks the invocations using an Invocation GUID. Requesting an invocation is an asynchronous operation.

Limitations 

The sections below detail current limitations of the invocation service. 

Primitive Type Arguments 

The Invocation Service can only invoke operations that use primitive types (the basic XML schema primitive types such as "string" and "int"). 

String Results 

ECHO returns the results of an invocation as the type "string".

Invocation State 

ECHO stores the state of an invocation using the Status Service and the invocation GUID. The following is a list of the states an invocation can enter:

Table 13: Invocation States

Client Operations 

This text below lists the operations of the Invocation Service that are specifically intended for end users. Other operations for Service Partners, like DelayInvocation and MarkAsynchronous, are detailed in the "Invocation Service Aware Web Services" section on the following page. For more information about Service Partners, refer to the forthcoming ECHO 10.10 Service Partner's Guide. 

Invoke Operation 

This operation submits a request to invoke an extended service operation. It is an asynchronous method so it returns an Invocation ID, used to track the progress of the invocation.

Arguments 

The operations and parameters on a web service registered in ECHO can be retrieved using the GetOperations method on the Extended Services Service. The web service implementation GUID, operation name, and parameters are sent to this operation. The web service implementation GUID must be the GUID of an activated web service implementation registered in ECHO. The operation name is the name of the operation to invoke on the web service. The number and names of the parameters must be correct. The order of the parameters is not important since the names must be unique. 

ECHO Path URI Parameters 

If you want to use metadata of granules or collections as parameter values when invoking an operation, then you should use ECHO Path URIs. ECHO Path URIs map to the metadata of a granule or collection. If a parameter value is a URI of the correct format, the URI will be resolved and the value retrieved from the metadata will be sent when invoking the web service.

The type retrieved from the metadata must be convertible to the parameter type in the operation; otherwise, the invocation will be aborted. For example if a parameter takes a float and the ECHO Path URI resolves to "ABZ" then invocation will be aborted. See Appendix D, ECHO Path URIs for more information. 

Returned Invocation GUID 

The return value is an invocation GUID used to track the invocation. The invocation GUID is passed into all the other methods of the Invocation Service to specify the invocation to which the user is referring. As the invocation is processed, the status is set using the Status Service. The Transaction GUID used in the Status Service is the same as the Invocation GUID. 

Get Results 

This returns the last state of the invocation and the results if the invocation has completed. The last status will include the current state of the invocation and any annotations to that state. The results will be included if the invocation state is COMPLETE. 

Service Partner Operations 

Service Partners can create web services that are Invocation Service-aware to gain extra abilities and provide more value to end users when being invoked by ECHO. A service called the Invocation Utility Service enables an Invocation Service-aware web service to delay an invocation, add status information on the invocation, or indicate that the web service is asynchronous. 

SOAP Header 

Invocation Service-aware web services know they are being invoked by ECHO because a special SOAP Header is passed in the SOAP request to invoke the operation. The information passed is the invocation GUID and the URL to the Invocation Utility Service. 

SOAP Header Layout 

This lists the major elements of the ECHO invocation SOAP header. The namespace of all these elements is  http://echo.nasa.gov/echotypes.

Table 14: Invocation SOAP Header Elements

SOAP Header Example 

This shows an example of what the SOAP header passed during an invocation by ECHO will look like. 

<soapenv:Header> 
	<ns1:EchoInvocation 
		soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" 
		soapenv:mustUnderstand="0" 
		xmlns:ns1="http://echo.nasa.gov/echoTypes"> 
		<ns1:invocationId 
			soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" 
			soapenv:mustUnderstand="0" 
			xsi:type="soapenc:string" 
			xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"> 
			88A3BDFB-FDA3-4BA6-F3CE-92D052284503 
		</ns1:invocationId> 
		<ns1:invocationUtilityUrl 
			soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" 
			soapenv:mustUnderstand="0" 
			xsi:type="soapenc:string" 
			xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"> 
			http://localhost:28000/echo_v8/InvocationUtilityService 
		</ns1:invocationUtilityUrl> 
	</ns1:EchoInvocation> 
</soapenv:Header>

Invocation Utility Service 

The Invocation Utility Service offers methods to Invocation-aware web services. 

Delay Invocation 

This operation delays the invocation until the specified date. This is useful if the web service does not currently have the resources available to process the invocation. ECHO will attempt to invoke the web service again at the specified date and time. See the section on Timing Concerns. 

Set Status 

This operation allows Invocation aware web services to provide detailed information to end users. The status string passed will be stored in ECHO under the current state of the invocation, which can be retrieved and viewed by users using the Invocation Service or Status Service. 

Mark Asynchronous 

This operation will mark the web service as being asynchronous. ECHO normally assumes when the operation returns that it is complete but if this operation is called, then the invocation state will stay in PERFORMING_INVOCATION until the web service notifies ECHO that it is complete using the Mark Complete operation. See the Timing Concerns section on timing concerns with this operation. 

Mark Complete 

This operation is used by asynchronous web services to notify ECHO that they are complete. The string results of the web service operation are an argument to this operation. Web services calling this method should have previously called the Mark Asynchronous operation.

Timing Concerns 

When a web service being invoked by ECHO returns, ECHO normally assumes the invocation is complete and immediately marks it that way. If a web service wants to delay the invocation or mark it asynchronous, it must call the Delay Invocation and Mark Asynchronous operations before returning from the original invocation. 

Invocation Sequence Diagrams 

This contains some sequence diagrams showing the steps that happen during a regular and asynchronous invocation. 

Normal Invocation Sequence Diagram

This diagram shows the normal sequence of steps when an invocation occurs.

Figure 19: ECHO Invocation Service Sequence

Asynchronous Invocation Sequence Diagram 

This diagram shows the sequence of steps when an invocation occurs on an asynchronous web service. 

Figure 20: Asynchronous Invocation Sequence